Custom Numeric Format Strings
A custom numeric format string, which you create and consists of one or more custom numeric format specifiers, defines how numeric data is formatted. A custom numeric format string is equivalently defined as any string that is not a standard numeric format string.
The following table describes the custom numeric format specifiers. For more information, see the notes that follow the table.
Format specifier
|
Name
|
Description
|
0
|
Zero placeholder
|
If the value being formatted has a digit in the position where the '0' appears in the format string, then that digit is copied to the result string; otherwise, a '0' appears in the result string. The position of the leftmost '0' before the decimal point and the rightmost '0' after the decimal point determines the range of digits that are always present in the result string.
The "00" specifier causes the value to be rounded to the nearest digit preceding the decimal, where rounding away from zero is always used. For example, formatting 34.5 with "00" would result in the value 35.
The following example displays several values formatted using custom format strings that include zero placeholders.
|
Строки настраиваемых числовых форматов19
Создаваемая строка настраиваемого числового формата состоит из одного или нескольких задаваемых спецификаторов числового формата и определяет, как форматируются числовые данные. Любая строка, не являющаяся строкой стандартного числового формата определяется как строка настраиваемого числового формата.
В следующей таблице описаны спецификаторы пользовательских числовых форматов. Дополнительные сведения содержатся в разделе примечания, расположенном после таблицы.
Описатель формата
|
Имя
|
Описание
|
0
|
Знак-заместитель нуля
|
Если форматируемое значение содержит цифру в позиции, где "0" находится в строке формата, то эта цифра копируется в выходную строку; в противном случае "0" отображается в выходной строке. Позиция крайнего левого "0" до десятичной точки и позиция крайнего правого "0" после десятичной точки определяют диапазон цифр, которые всегда включаются в выходную строку.
Спецификатор "00" приводит к округлению значения до ближайшего значения цифры, предшествующей десятичной точке-разделителю, если назначено использование округления от нуля. Например, в результате форматирования числа 34,5 с помощью строки "00" будет получена строка со значением"35".
В следующем примере показано форматирование нескольких значений с помощью строк пользовательского формата, содержащих знаки-заместители нуля.
|
double value;
value = 123;
Console.WriteLine(value.ToString("00000"));
// Displays 00123
value = 1.2;
Console.WriteLine(value.ToString("0.00", CultureInfo.InvariantCulture));
// Displays 1.20
Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture));
// Displays 01.20
Console.WriteLine(value.ToString("00.00",
CultureInfo.CreateSpecificCulture("da-DK")));
// Displays 01,20
value = .56;
Console.WriteLine(value.ToString("0.0", CultureInfo.InvariantCulture));
// Displays 0.6
value = 1234567890;
Console.WriteLine(value.ToString("#,#", CultureInfo.InvariantCulture));
// Displays 1,234,567,890
Console.WriteLine(value.ToString("#,#",
CultureInfo.CreateSpecificCulture("el-GR")));
// Displays 1.234.567.890
double value;
value = 123;
Console.WriteLine(value.ToString("00000"));
// Displays 00123
value = 1.2;
Console.WriteLine(value.ToString("0.00", CultureInfo.InvariantCulture));
// Displays 1.20
Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture));
// Displays 01.20
Console.WriteLine(value.ToString("00.00",
CultureInfo.CreateSpecificCulture("da-DK")));
// Displays 01,20
value = .56;
Console.WriteLine(value.ToString("0.0", CultureInfo.InvariantCulture));
// Displays 0.6
value = 1234567890;
Console.WriteLine(value.ToString("#,#", CultureInfo.InvariantCulture));
// Displays 1,234,567,890
Console.WriteLine(value.ToString("#,#",
CultureInfo.CreateSpecificCulture("el-GR")));
// Displays 1.234.567.890
#
|
Digit placeholder
|
If the value being formatted has a digit in the position where the '#' appears in the format string, then 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 the '0' character if it is not a significant digit, even if '0' is the only digit in the string. It will display the '0' character if it is a significant digit in the number 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. For example, formatting 34.5 with "##" would result in the value 35.
The following example displays several values formatted using custom format strings that include digit placeholders.
double value;
value = 1.2;
Console.WriteLine(value.ToString("#.##", CultureInfo.InvariantCulture));
// Displays 1.2
value = 123;
Console.WriteLine(value.ToString("#####"));
// Displays 123
value = 123456;
Console.WriteLine(value.ToString("[##-##-##]"));
// Displays [12-34-56]
value = 1234567890;
Console.WriteLine(value.ToString("#"));
// Displays 1234567890
Console.WriteLine(value.ToString("(###) ###-####"));
// Displays (123) 456-7890
|
|
#
|
Заместитель цифры
|
Цифра, расположенная в соответствующей позиции форматируемого значения будет скопирована в выходную строку, если в этой позиции в строке формата присутствует знак "#". В противном случае в выходной строке на этой позиции ничего не записывается.
Обратите внимание, что ноль не будет отображен, если он не является значащей цифрой, даже если это единственный знак строки. Ноль отображается, только если он является значащей цифрой форматируемого значения.
Строка формата "##" приводит к округлению значения до ближайшего значения цифры, предшествующей десятичному разделителю, если назначено использование округления от нуля. Например, в результате форматирования числа 34,5 с помощью строки "##" будет получена строка со значением "35".
В следующем примере показано форматирование нескольких значений с помощью строк пользовательского формата, содержащих заместители цифр.
|
----------
.
|
Decimal point
|
The first '.' character in the format string determines the location of the decimal separator in the formatted value; any additional '.' characters are ignored.
The actual character used as the decimal separator in the result string is determined by the NumberDecimalSeparator property of the NumberFormatInfo object that controls formatting.
The following example uses the decimal point format specifier to define the location of the decimal point in several result strings.
double value;
value = 1.2;
Console.WriteLine(value.ToString("0.00", CultureInfo.InvariantCulture));
// Displays 1.20
Console.WriteLine(value.ToString("00.00", CultureInfo.InvariantCulture));
// Displays 01.20
Console.WriteLine(value.ToString("00.00",
CultureInfo.CreateSpecificCulture("da-DK")));
// Displays 01,20
value = .086;
Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture));
// Displays 8.6%
value = 86000;
Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture));
// Displays 8.6E+4
|
|
.
|
Разделитель
|
Первый знак "." определяет расположение разделителя целой и дробной частей, дополнительные знаки "." игнорируются.
Фактический символ, используемый в качестве десятичного разделителя в выходной строке определяется свойством NumberDecimalSeparator объекта NumberFormatInfo, управляющего форматированием.
В следующем примере спецификатор формата десятичний точки используется для определения местоположения десятичной точки в нескольких выходных строках.
|
------------
,
|
Thousand separator and number scaling
|
The ',' character serves as both a thousand separator specifier and a number scaling specifier.
Thousand separator specifier: If one or more ',' characters is 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.
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. For example, if the string "#,#" and the invariant culture are used to format the number 1000, the output is "1,000".
Number scaling specifier: If one or more ',' characters is specified immediately to the left of the explicit or implicit decimal point, the number to be formatted is divided by 1000 each time a number scaling specifier occurs. For example, if the string "0,," is used to format the number 100 million, the output is "100".
You can use thousand separator and number scaling specifiers in the same format string. 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 thousand separator.
double value = 1234567890;
Console.WriteLine(value.ToString("#,#", CultureInfo.InvariantCulture));
// Displays 1,234,567,890
Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture));
// Displays 1,235
|
The following example illustrates the use of the comma as a specifier for number scaling.
double value = 1234567890;
Console.WriteLine(value.ToString("#,,", CultureInfo.InvariantCulture));
// Displays 1235
Console.WriteLine(value.ToString("#,,,", CultureInfo.InvariantCulture));
// Displays 1
Console.WriteLine(value.ToString("#,##0,,", CultureInfo.InvariantCulture));
// Displays 1,235
|
|
,
|
Разделитель числовых разрядов и масштабирование чисел
|
Символ "," служит в качестве спецификатора разделителя числовых разрядов и спецификатора масштабирования чисел.
Спецификатор разделителя числовых разрядов: Если один или несколько символов "," указаны между двумя заместителями цифр (0 или #), которые форматируют целые разряды числа, то символ разделителя групп вставляется между каждой группой числа в составной части выходных данных.
Свойства NumberGroupSeparator и NumberGroupSizes текущего объекта NumberFormatInfo определяют знак, используемый в качестве разделителя групп числа и размера каждой группы числа. Например, если строка "#,#" и неизменяемый язык и региональные параметры используются для форматирования числа 1000, то результатом является "1,000".
Спецификатор масштабирования чисел: Если один или несколько символов "," указаны непосредственно слева от явной или неявной десятичной точки, то форматируемое число делится на 1000 каждый раз, когда встречается спецификатор масштабирования числа. Например, если строка "0,," используется для форматирования числа 100 миллионов, то результатом является "100".
Можно использовать разделитель числовых разрядов и спецификатор масштабирования числа в одной строке формата. Например, если строка "#, 0,," и неизменяемый язык и региональные параметры используются для форматирования числа один миллиард, то результатом является "1,000".
Следующий пример иллюстрирует использование запятой в качестве разделителя
|
------
Следующий пример иллюстрирует использование запятой как спецификатора масштабирования числа.
---------
%
|
Percentage placeholder
|
The presence of a '%' character in a format string causes a number to be multiplied by 100 before it is formatted. The appropriate symbol is inserted in the number itself at the location where the '%' appears in the format string. The percent character used is dependent on the current NumberFormatInfo class.
The following example defines several custom format strings that include the percentage placeholder.
double value = .086;
Console.WriteLine(value.ToString("#0.##%", CultureInfo.InvariantCulture));
// Displays 8.6%
|
|
E0
E+0
E-0
e0
e+0
e-0
|
Scientific notation
|
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 '0' character, then the number is formatted using scientific notation with an 'E' or 'e' inserted between the number and the exponent. The number of '0' characters following the scientific notation indicator determines the minimum number of digits to output for the exponent. The "E+" and "e+" formats indicate that a sign character (plus or minus) should always precede the exponent. The "E", "E-", "e", or "e-" formats indicate that a sign character should only precede negative exponents.
The following example formats several numeric values using the specifiers for scientific notation.
double value = 86000;
Console.WriteLine(value.ToString("0.###E+0", CultureInfo.InvariantCulture));
// Displays 8.6E+4
Console.WriteLine(value.ToString("0.###E+000", CultureInfo.InvariantCulture));
// Displays 8.6E+004
Console.WriteLine(value.ToString("0.###E-000", CultureInfo.InvariantCulture));
// Displays 8.6E004
|
|
%
|
Заместитель процентов
|
При использовании знака "%" в строке форматирования число будет умножено на 100. В соответствующую позицию выходной строки будет вставлен знак "%". Знак процента определяется текущим классом NumberFormatInfo.
В следующем примере определяется несколько строк пользовательского формата, включающих в себя заместитель процента.
|
--------
E0
E+0
E-0
e0
e+0
e-0
|
Экспоненциальное представление чисел
|
Если в строке формата присутствует один из знаков "E", "E+", "E-", "e", "e+" или "e-", за которым следует по крайней мере один знак "0", число представляется в экспоненциальной форме; между числом и экспонентой вставляется знак "E" или "e". Минимальная длина экспоненты в строке вывода определяется количеством нулей, расположенных за знаком формата. Знаки "E+" и "e+" устанавливают обязательное отображение знака "плюс" или "минус" перед экспонентой. Знаки "E", "e", "E-" и "e-" устанавливают отображение знака только для отрицательных чисел.
В следующем примере несколько числовых значений форматируются с помощью спецификаторов экспоненциального представления.
|
--------------
\
|
Escape character
|
In C# and C++, the backslash character causes the next character in the format string to be interpreted as an escape sequence. It is used with traditional formatting sequences like '\n' (new line).
In some languages, the escape character itself must be preceded by an escape character when used as a literal. Otherwise, the compiler interprets the character as an escape sequence. Use the string "\\" to display '\'.
|
'ABC'
"ABC"
|
Literal string
|
Characters enclosed in single or double quotes are copied to the result string, and do not affect formatting.
|
;
|
Section separator
|
The ';' character is used to separate sections for positive, negative, and zero numbers in the format string. If there are two sections in the custom format string, the leftmost section defines the formatting of positive and zero numbers, while the rightmost section defines the formatting of negative numbers. If there are three sections, the leftmost section defines the formatting of positive numbers, the middle section defines the formatting of zero numbers, and the rightmost section defines the formatting of negative numbers.
The following example uses the format specifier for the section separator to format positive, negative, and zero numbers differently.
double posValue = 1234;
double negValue = -1234;
string fmt = "##;(##)";
Console.WriteLine(posValue.ToString(fmt)); // Displays 1234
Console.WriteLine(negValue.ToString(fmt)); // Displays (1234)
|
|
\
|
Символ начала управляющей последовательности
|
В C# и C++ символ, следующий в строке формата за обратной косой чертой, воспринимается как escape-последовательность. Этот символ используется с обычными последовательностями форматирования (например, \n — новая строка).
Чтобы использовать обратную косую черту как символ, в некоторых языках ее необходимо повторить. В противном случае символ будет интерпретирован компилятором как начало управляющей последовательности. Чтобы отобразить обратную косую черту, используйте строку с "\\".
Обратите внимание, что символ начала управляющей последовательности не поддерживается в Visual Basic, однако объект ControlChars обладает аналогичными функциями.
|
'ABC'
"ABC"
|
Символьная строка
|
Символы, заключенные в одинарные или двойные кавычки, копируются в выходную строку без форматирования.
|
;
|
Разделитель секций
|
Знак ";" служит для разделения секций положительных, отрицательных и нулевых чисел в строке формата. Если в строке пользовательского формата две секции, то крайняя левая секция определяет форматирование положительных чисел и нулей, а крайняя правая – форматирование отрицательных чисел. Если в строке пользовательского формата три секции, то крайняя левая секция определяет форматирование положительных чисел, средняя секция определяет форматирование нулей, а крайняя правая – форматирование отрицательных чисел.
В следующем примере используется спецификатор формата для разделителей секций положительных, отрицательных и нулевых чисел.
|
---------------
Notes
Floating-Point Infinities and NaN
Note that 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. 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 using different settings will generate different result strings.
Rounding and Fixed-Point Format Strings
Note that 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.
Примечания
Бесконечности действительных чисел с плавающей запятой и NaN
Обратите внимание, что независимо от строки формата, если значение типа с плавающей запятойSingle или Double является плюс бесконечностью, минус бесконечностью или не является числом (NaN), в отформатированной строке является значением соответствующим PositiveInfinitySymbol, NegativeInfinitySymbol, или свойству NaNSymbol, которые указаны в данный момент соответствующим объектом NumberFormatInfo.
Настройки панели управления
Параметры элемента панели управления Язык и региональные стандарты влияют на выходную строку, получаемую в результате операции форматирования. Эти параметры используются для инициализации объекта NumberFormatInfo, связанного с текущей культурой потока, а текущая культура потока предоставляет значения, которые используются для управления форматированием. Результирующие строки будут различаться на компьютерах с разными настройками.
Строки формата с фиксированной запятой и округлением
Обратите внимание, что строки формата с фиксированной запятой (т.е. не содержащие символов экcпоненциального представления) округляют значение с точностью, заданной количеством знаков-заместителей справа от десятичной точки. Если в строке формата нет десятичной точки, то число округляется до ближайшего целого значения. Если слева от десятичной точки больше цифр, чем знаков-заместителей цифр, то лишние знаки копируются в выходную строку перед первым знаком-заместителем цифры.
Section Separators and Conditional Formatting
Different formatting can be applied to a string based on whether the 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.
Number of sections
|
Description
|
One section
|
The format string applies to all values.
|
Two sections
|
The first section applies to positive values and zeros, and the second section applies to negative values.
If the number to be formatted is negative, but becomes zero after rounding according to the format in the second section, then the resulting zero is formatted according to the first section.
|
Three sections
|
The first section applies to positive values, the second section applies to negative values, and the third section applies to zeros.
The second section can be left empty (by having nothing between the semicolons), in which case the first section applies to all nonzero values.
If the number to be formatted is nonzero, but becomes zero after rounding according to the format in the first or second section, then the resulting zero is formatted according to the third section.
|
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 code fragments illustrate how section separators can be used to produce formatted strings.
Разделители секций и условное форматирование20
К строке может быть применено различное форматирование в зависимости от того, является ли значение положительным, отрицательным или нулевым. Для этого следует создать строку формата, состоящую из трех секций, разделенных точкой с запятой. Эти секции описаны в следующей таблице.
Число секций
|
Описание
|
Одна секция
|
Строка форматирования применяется ко всем значениям.
|
Две секции
|
Первая секция применяется для положительных значений и нулей, вторая секция применяется для отрицательных значений.
Если форматируемое число является отрицательным, но становится нулем в результате округления в соответствии с форматированием, то ноль форматируется в соответствии с первой секцией.
|
Три секции
|
Первая секция применяется для положительных значений, вторая секция применяется для отрицательных значений, а третья — для нулей.
Вторая секция может быть пустой (между двумя точками с запятой пусто), в этом случае первая секция будет использоваться для форматирования нулевых значений.
Если форматируемое число является ненулевым, но становится нулем в результате округления в соответствии с форматированием в первой или второй секции, то ноль форматируется в соответствии с третьей секцией.
|
При форматировании конечного значения разделители секций игнорируют любое существовавшее ранее форматирование, связанное с числом. Например, при использовании разделителей секций отрицательные значения всегда отображаются без знака "минус". Чтобы конечное отформатированное значение содержало знак "минус", его следует явным образом включить в настраиваемый спецификатор формата.
В следующих фрагментах кода демонстрируется применение разделителей секций для создания строк форматирования.
double MyPos = 19.95, MyNeg = -19.95, MyZero = 0.0;
// In the U.S. English culture, MyString has the value: $19.95.
string MyString = MyPos.ToString("$#,##0.00;($#,##0.00);Zero");
// In the U.S. English culture, MyString has the value: ($19.95).
// The minus sign is omitted by default.
MyString = MyNeg.ToString("$#,##0.00;($#,##0.00);Zero");
// In the U.S. English culture, MyString has the value: Zero.
MyString = MyZero.ToString("$#,##0.00;($#,##0.00);Zero");
Two Custom Format Examples
The following code fragments demonstrate custom numeric formatting. In both cases the digit placeholder (#) in the custom format string displays the numeric data, and all other characters are copied to the output.
Double myDouble = 1234567890;
String myString = myDouble.ToString( "(###) ### - ####" );
// The value of myString is "(123) 456 – 7890".
int MyInt = 42;
MyString = MyInt.ToString( "My Number = #" );
// In the U.S. English culture, MyString has the value:
// "My Number = 42".
|
double MyPos = 19.95, MyNeg = -19.95, MyZero = 0.0;
// In the U.S. English culture, MyString has the value: $19.95.
string MyString = MyPos.ToString("$#,##0.00;($#,##0.00);Zero");
// In the U.S. English culture, MyString has the value: ($19.95).
// The minus sign is omitted by default.
MyString = MyNeg.ToString("$#,##0.00;($#,##0.00);Zero");
// In the U.S. English culture, MyString has the value: Zero.
MyString = MyZero.ToString("$#,##0.00;($#,##0.00);Zero");
|
Два примера настраиваемых форматов
В следующих фрагментах кода демонстрируется настраиваемое форматирование чисел. В обоих случаях заменитель цифры (#) в строке пользовательского формата отображает числовые данные, а все остальные знаки копируются в выходную строку.
Double myDouble = 1234567890;
String myString = myDouble.ToString( "(###) ### - ####" );
// The value of myString is "(123) 456 – 7890".
int MyInt = 42;
MyString = MyInt.ToString( "My Number = #" );
// In the U.S. English culture, MyString has the value:
// "My Number = 42".
|
|
