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

Строки стандартных числовых форматов служат для форматирования стандартных числовых типов. Строка стандартных числовых форматов использует формат [format specifier][precision specifier] , где:

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

Описатель точности — это необязательное целое число, которое влияет на количество цифр в результирующей строке. В .NET 6 и более поздних версиях максимальное значение точности равно Int32.MaxValue . В предыдущих версиях .NET точность может варьироваться от 0 до 99. Спецификатор точности управляет количеством цифр в строковом представлении числа. Он не округляет само число. Для выполнения операции округления используйте метод Math.Ceiling, Math.Floor или Math.Round.

Когда указатель точности ограничивает число цифр дробной части в итоговой строке, числа в итоговых строках округляются до представимого результата, ближайшего к бесконечно точному. Если имеются два одинаково близких представимых результата:

• в платформа .NET Framework и .net core до .net core 2,0среда выполнения выбирает результат с более поздней значащий цифрой (то есть с помощью ).
• В .NET Core 2,1 и более поздних версияхсреда выполнения выбирает результат с использованием хотя бы значимой цифры (то есть с помощью ).

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

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

Некоторые перегрузки метода ToString для всех числовых типов. Например, можно задать строку числового формата для методов Int32.ToString(String) и Int32.ToString(String, IFormatProvider).

Функция составного форматирования.NET, которая используется некоторыми методами Console и WriteLine классами и StreamWriter , String.Format методами и StringBuilder.AppendFormat методом. Композитный формат позволяет включить строковое представление нескольких элементов данных в одну строку, чтобы задать ширину поля и выровнять числа в поле. Дополнительные сведения см. в разделе Составное форматирование.

Интерполированные строки в C# и Visual Basic, которые предоставляют упрощенный синтаксис по сравнению со строками составного формата.

Вы можете загрузить служебную программу форматирования — приложение Windows Forms для .NET Core, позволяющее применять строки формата к значениям даты и времени и числовым значениям и отображающее результирующую строку. Исходный код доступен для C# и Visual Basic.

Стандартные описатели формата

В следующей таблице описаны спецификаторы стандартных числовых форматов и отображены примеры выходных данных, производимых каждым спецификатором формата. Дополнительные сведения об использовании строк стандартных числовых форматов см. в разделе « Примечания », а также в разделе « пример кода ».

Результат форматированной строки для определенного языка и региональных параметров может отличаться от следующих примеров. Параметры операционной системы, параметры пользователя, переменные среды и используемая версия .NET могут влиять на формат. Например, начиная с .NET 5, .NET пытается унифицировать культурные форматы на разных платформах. Дополнительные сведения см. в разделе .NET Globalization and ICU.

Описатель формата name Описание Примеры "C" или "c" Валюта Результат: ; значение валюты.

Поддерживается в: все числовые типы.

Описатель точности: число десятичных разрядов.

Описатель точности по умолчанию: Определяется в NumberFormatInfo.CurrencyDecimalDigits.

123,456 ("C", fr-FR)- > 123, 46 €

-123,456 ("C3", fr-FR)- > -€123 456

Поддерживается в: только целочисленные типы.

Описатель точности: минимальное число разрядов.

Описатель точности по умолчанию: минимальное требуемое число разрядов.

Поддерживается в: все числовые типы.

Описатель точности: число десятичных разрядов.

Описатель точности по умолчанию: 6.

1052,0329112756 ("e", fr-FR)- > 1, 052033e + 003

-1052,0329112756 ("E2", EN-US)- > -1,05 e + 003

Поддерживается в: все числовые типы.

Описатель точности: число десятичных разрядов.

Описатель точности по умолчанию: Определяется в NumberFormatInfo.NumberDecimalDigits.

1234,567 ("F", de-DE)- > 1234, 57

1234 ("F1", de-DE)- > 1234, 0

-1234,56 ("F4", EN-US)- > -1234,5600

Поддерживается в: все числовые типы.

Описатель точности: количество значащих цифр.

Описатель точности по умолчанию: зависит от числового типа.

-123,456 ("G", SV-SE)- > -123 456

123,4546 ("G4", EN-US)— > 123,5

123,4546 ("G4", SV-SE)- > 123, 5

-1.234567890 e-25 ("G", EN-US)- > -1.23456789 e-25

Поддерживается в: все числовые типы.

Описатель точности: желаемое число десятичных разрядов.

Описатель точности по умолчанию: Определяется в NumberFormatInfo.NumberDecimalDigits.

1234,567 ("N", ru-RU)- > 1 234, 57

1234 ("N1", EN-US)— > 1 234,0

1234 ("N1", ru-RU)- > 1 234, 0

-1234,56 ("N3", EN-US)- > -1 234,560

Поддерживается в: все числовые типы.

Описатель точности: желаемое число десятичных разрядов.

Описатель точности по умолчанию: Определяется в NumberFormatInfo.PercentDecimalDigits.

Примечание. Мы рекомендуем использовать только для типа BigInteger. Для типов Double используйте "G17", а для типов Single — "G9". Описатель точности: Не обрабатывается.

Поддерживается в: только целочисленные типы.

Описатель точности: число цифр в результирующей строке.

Использовать строки стандартных числовых форматов

Примеры C# в этой статье выполняются во встроенном средстве выполнения кода и на площадке Try.NET. Нажмите на кнопку Выполнить, чтобы выполнить пример в интерактивном окне. После выполнения кода вы можете изменить его и выполнить измененный код, снова нажав на кнопку Выполнить. Либо в интерактивном окне выполняется измененный код, либо, если компиляция завершается с ошибкой, в интерактивном окне отображаются все сообщения об ошибках компилятора C#.

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

Его можно передать TryFormat в метод или перегрузку ToString метода, имеющего format параметр. В следующем примере осуществляется форматирование числового значения в качестве строки со значением валюты для текущего языка и региональных параметров (en-US).

Эту строку можно передать в качестве аргумента formatString в элемент форматирования, используемый с методами String.Format, Console.WriteLine и StringBuilder.AppendFormat. Дополнительные сведения см. в разделе Составное форматирование. В следующем примере элемент форматирования используется для вставки значения валюты в строку.

При желании вы можете передать аргумент alignment , чтобы указать ширину числового поля и установить выравнивание по правому или левому краю. В следующем примере денежное значение в поле длиной 28 символов выравнивается по левому краю, а денежное значение в поле длиной 14 символов выравнивается по правому краю.

Его можно предоставить в виде аргумента formatString в элементе интерполированного выражения интерполированной строки. дополнительные сведения см. в статье интерполяция строк в справочнике по C# или в статье с интерполяцией строк в справочнике по Visual Basic.

В приведенных ниже разделах содержится подробная информация о всех строках стандартных числовых форматов.

Описатель формата валюты (C)

При использовании описателя формата валюты ("C") число преобразуется в строку, представляющую сумму в некоторой валюте. Желаемое количество знаков дробной части в результирующей строке задается описателем точности. Если описатель точности не задан, точность по умолчанию определяется свойством NumberFormatInfo.CurrencyDecimalDigits.

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

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

Свойство NumberFormatInfo Описание CurrencyPositivePattern Определяет положение символа валюты в положительных значениях. CurrencyNegativePattern Определяет положение символа валюты в отрицательных значениях и указывает, как именно представляется отрицательный знак: круглыми скобками или свойством NegativeSign. NegativeSign Задает отрицательный знак, используемый в случае, если свойство CurrencyNegativePattern указывает на то, что скобки для отрицания не используются. CurrencySymbol Определяет символ валюты. CurrencyDecimalDigits Определяет количество цифр дробной части в значении валюты по умолчанию. Это значение можно переопределить с помощью описателя точности. CurrencyDecimalSeparator Определяет строку, разделяющую целую и дробную части числа. CurrencyGroupSeparator Определяет строку, разделяющую группы цифр целой части. CurrencyGroupSizes Определяет число целочисленных цифр, входящих в группу.

В следующем примере значение Double форматируется с помощью описателя денежного формата:

Спецификатор десятичного формата (D)

При использовании описателя десятичного формата ("D") число преобразуется в строку, состоящую из десятичных цифр (0–9); если число отрицательное, перед ним ставится отрицательный знак. Этот формат доступен только для целых типов.

Минимальное количество знаков в выходной строке задается спецификатором точности. Недостающие знаки в строке заменяются нулями. Если описатель точности не задан, по умолчанию используется минимальное значение, позволяющее представить целое число без нулей в начале.

Форматирование результирующей строки определяется сведениями о форматировании в текущем объекте NumberFormatInfo. Как показано в следующей таблице, управление форматированием результирующей строки осуществляется с помощью одного свойства.

Свойство NumberFormatInfo Описание NegativeSign Определяет строку, указывающую, что число является отрицательным.

В следующем примере значение Int32 форматируется с помощью описателя десятичного формата.

Описатель экспоненциального формата (E)

При использовании описателя экспоненциального формата ("E") число преобразуется в строку вида "-d.ddd…E+ddd" или "-d.ddd…e+ddd", где каждый символ "d" обозначает цифру (0–9). Если число отрицательное, в начале строки ставится отрицательный знак. Перед разделителем целой и дробной части всегда стоит ровно одна цифра.

Требуемое число знаков дробной части задается спецификатором точности. Если спецификатор точности отсутствует, по умолчанию число знаков дробной части равно шести.

Регистр описателя формата задает регистр буквы, стоящей перед экспонентой ("E" или "e"). Экспонента состоит из знака "плюс" или "минус" и трех цифр. Недостающие до минимума цифры заменяются нулями, если это необходимо.

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

Свойство NumberFormatInfo Описание NegativeSign Определяет строку, указывающую на то, что число является отрицательным (как мантисса, так и экспонента). NumberDecimalSeparator Определяет строку, разделяющую целую и дробную части мантиссы. PositiveSign Определяет строку, указывающую, что экспонента является положительной.

В следующем примере значение Double форматируется с помощью описателя экспоненциального формата.

Описатель формата с фиксированной запятой (F)

При использовании описателя формата с фиксированной запятой ("F") число преобразуется в строку вида "-ddd.ddd…", где каждый символ "d" обозначает цифру (0–9). Если число отрицательное, в начале строки ставится отрицательный знак.

Требуемое число знаков дробной части задается спецификатором точности. Если описатель точности отсутствует, то используется численная точность, определяемая текущим значением свойства NumberFormatInfo.NumberDecimalDigits.

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

Свойство NumberFormatInfo Описание NegativeSign Определяет строку, указывающую, что число является отрицательным. NumberDecimalSeparator Определяет строку, разделяющую целую и дробную части числа. NumberDecimalDigits Определяет количество цифр дробной части по умолчанию. Это значение можно переопределить с помощью описателя точности.

В следующем примере значение Double и значение Int32 форматируются с помощью описателя формата с фиксированной точкой.

Общий описатель формата (G)

При использовании описателя общего формата ("G") число преобразуется в более короткий из двух вариантов: запись с фиксированной запятой или экспоненциальная запись. При этом учитывается тип числа и наличие описателя точности. Описатель точности определяет максимальное количество значащих цифр, которые могут быть использованы в результирующей строке. Если описатель точности не задан или равен нулю, точность определяется типом числа, как показано в следующей таблице.

Числовой тип Точность по умолчанию Byte или SByte 3 знака Int16 или UInt16 5 знака Int32 или UInt32 10 знака Int64 19 знака UInt64 20 знака BigInteger Без ограничений (то же, что и R) Half 3 знака Single 7 знака Double 15 знака Decimal 29 знака

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

Тем не менее, если число относится к типу Decimal и описатель точности не задан, всегда используется нотация с фиксированной запятой, а нули в конце не отбрасываются.

Если используется экспоненциальная нотация, регистр буквы, стоящей перед экспонентой, определяется регистром описателя формата (буква "E" соответствует "G", "e" соответствует "g"). Экспонента содержит не менее двух цифр. Это отличает данный формат от экспоненциальной записи, создаваемой при использовании описателя экспоненциального формата, поскольку в последнем случае экспонента содержит не менее трех цифр.

При использовании со Double значением описатель формата "G17" гарантирует, что исходное Double значение успешно обходовется. Это связано с тем Double , что — это число с плавающей запятой, совместимое binary64 с IEEE 754-2008, которое обеспечивает до 17 значащих цифр точности. в платформа .NET Framework рекомендуется использовать вместо описателя формата "r", поскольку в некоторых случаях "R" не удается успешно выполнить циклический обмен значениями с плавающей запятой двойной точности.

При использовании со значением Single описатель формата G9 гарантирует обратимость преобразования исходного значения Single. Это связано с тем Single , что является числом с плавающей запятой, СООТВЕТСТВУЮЩИМ binary32 стандарту IEEE 754-2008, которое обеспечивает до девяти значащих цифр точности. Из соображений производительности рекомендуется использовать его вместо описателя формата "R".

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

Свойство NumberFormatInfo Описание NegativeSign Определяет строку, указывающую, что число является отрицательным. NumberDecimalSeparator Определяет строку, разделяющую целую и дробную части числа. PositiveSign Определяет строку, указывающую, что экспонента является положительной.

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

Описатель числового формата (N)

Спецификатор числового формата ("N") преобразует число в стоку вида "-d,ddd,ddd.ddd… ", где знак "-" при необходимости представляет знак отрицательного числа, знак "d" означает цифру (0-9), знак "," — разделитель групп, а знак "." —- разделитель целой и дробной части. Требуемое число знаков дробной части задается спецификатором точности. Если описатель точности не задан, число десятичных знаков определяется текущим свойством NumberFormatInfo.NumberDecimalDigits.

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

Свойство NumberFormatInfo Описание NegativeSign Определяет строку, указывающую, что число является отрицательным. NumberNegativePattern Определяет формат отрицательных значений и указывает, как именно представляется отрицательный знак: круглыми скобками или свойством NegativeSign. NumberGroupSizes Определяет число цифр целой части, стоящих между разделителями групп. NumberGroupSeparator Определяет строку, разделяющую группы цифр целой части. NumberDecimalSeparator Определяет строку, разделяющую целую и дробную части числа. NumberDecimalDigits Определяет количество цифр дробной части по умолчанию. Это значение можно переопределить с помощью описателя точности.

В следующем примере различные значения с плавающей запятой форматируются с помощью описателя числового формата.

Описатель формата процентов (P)

При использовании описателя формата процента ("P") число умножается на 100 и преобразуется в строку, представляющую процентную долю. Требуемое число знаков дробной части задается спецификатором точности. Если описатель точности отсутствует, то используется значение точности числа по умолчанию, заданное свойством PercentDecimalDigits.

В следующей таблице представлены свойства NumberFormatInfo, обеспечивающие управление форматированием возвращаемой строки.

Свойство NumberFormatInfo Описание PercentPositivePattern Определяет положение символа процента в положительных значениях. PercentNegativePattern Определяет положение символа процента и отрицательного знака в отрицательных значениях. NegativeSign Определяет строку, указывающую, что число является отрицательным. PercentSymbol Определяет символ процента. PercentDecimalDigits Определяет количество цифр дробной части в значении процента по умолчанию. Это значение можно переопределить с помощью описателя точности. PercentDecimalSeparator Определяет строку, разделяющую целую и дробную части числа. PercentGroupSeparator Определяет строку, разделяющую группы цифр целой части. PercentGroupSizes Определяет число целочисленных цифр, входящих в группу.

В следующем примере значения с плавающей запятой форматируются с помощью описателя процентного формата.

Описатель формата приема-передачи (R)

Описатель формата обратного преобразования ("R") пытается выполнить преобразование числового значения в строку так, чтобы при обратном преобразовании этой строки можно было получить то же самое числовое значение. Этот формат поддерживается только для Half типов, Single , Double и BigInteger .

Для значений Double описатель формата "R" в некоторых случаях не может гарантировать правильное обратное преобразование. Для значений Double и Single он также обеспечивает относительно низкую производительность. Вместо этого рекомендуется использовать описатель формата "G17" для значений и описатель формата "G9" для успешного приема значений кругового пути.

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

Хотя описатель точности можно указать, он будет проигнорирован. Приведенные указатели приема-передачи в данном случае имеют преимущество перед указателем точности. Форматирование результирующей строки определяется сведениями о форматировании в текущем объекте NumberFormatInfo. В следующей таблице представлены свойства NumberFormatInfo, обеспечивающие управление форматированием результирующей строки.

Свойство NumberFormatInfo Описание NegativeSign Определяет строку, указывающую, что число является отрицательным. NumberDecimalSeparator Определяет строку, разделяющую целую и дробную части числа. PositiveSign Определяет строку, указывающую, что экспонента является положительной.

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

В некоторых случаях для значений Double, отформатированных с использованием строки стандартного числового формата "R", не удается успешно выполнить обратное преобразование при компиляции с использованием параметра /platform:x64 или /platform:anycpu и запуска в 64-разрядных системах. Дополнительные сведения см. в следующем абзаце.

Чтобы избежать проблемы со значениями Double, отформатированными с использованием строки стандартного числового формата R, для которых не удалось выполнить обратное преобразование при компиляции с использованием параметра /platform:x64 или /platform:anycpu в 64-разрядных системах, можно отформатировать значения Double с помощью строки стандартного числового формата G17. В примере ниже используется строка формата "R" со значением Double, для которого не удается выполнить обратное преобразование, а также строка формата "G17" для успешного обратного преобразования исходного значения:

Спецификатор шестнадцатеричного формата (X)

При использовании описателя шестнадцатеричного формата ("X") число преобразуется в строку шестнадцатеричных цифр. Регистр шестнадцатеричных цифр больше 9 совпадает с регистром описателя формата. Например, чтобы получить запись "ABCDEF", задайте описатель X" или, наоборот, задайте описатель "x", чтобы получить "abcdef". Этот формат доступен только для целых типов.

Минимальное количество знаков в выходной строке задается спецификатором точности. Недостающие знаки в строке заменяются нулями.

Форматирование результирующей строки не зависит от сведений о форматировании в текущем объекте NumberFormatInfo.

В следующем примере значения Int32 форматируются с помощью спецификатора шестнадцатеричного формата.

Примечания

В этом разделе содержатся дополнительные сведения об использовании строк стандартных числовых форматов.

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

Кроме того, если CultureInfo(String) конструктор используется для создания экземпляра нового CultureInfo объекта, представляющего ту же культуру, что и текущий язык и региональные параметры системы, все настройки, установленные с помощью элемента язык CultureInfo(String) в панели управления, будут применены к новому CultureInfo объекту. Можно воспользоваться конструктором CultureInfo(String, Boolean) для создания объекта CultureInfo , который не отражает настройки системы.

На форматирование влияют свойства текущего NumberFormatInfo объекта, которые неявно предоставляются текущим языком и региональными параметрами или явно IFormatProvider в параметре метода, который вызывает форматирование. Укажите объект NumberFormatInfo или объект CultureInfo для этого параметра.

Дополнительные сведения о настройке шаблонов или строк, используемых в форматировании числовых значений см. статью о классе NumberFormatInfo.

Некоторые описания спецификаторов стандартных числовых форматов относятся к целочисленным типам и типам с плавающей запятой. Целочисленные типы — это Byte, SByte, Int16, Int32, Int64, UInt16, UInt32, UInt64 и BigInteger. Числовые типы с плавающей запятой: Decimal , Half , Single и Double .

Независимо от строки формата, если значение Half типа, Single или Double с плавающей запятой является положительной бесконечностью, отрицательной бесконечностью или не является числом (NaN), отформатированная строка является значением соответствующего PositiveInfinitySymbol свойства, или NaNSymbol , которое указано в текущем объекте, NegativeInfinitySymbol применимом NumberFormatInfo в настоящий момент.

Пример кода

В следующем примере с помощью языка и региональных параметров "en-US" и всех описателей стандартных числовых форматов форматируется целочисленное значение и числовое значение с плавающей запятой. В этом примере используются два отдельных числовых типа ( Double и), но они выдают аналогичные результаты для любого другого числового базового типа ( Byte , Int16SByte ,, Int64UInt16Int32UInt32 . UInt64 , DecimalBigIntegerHalf ,, и Single ). Int32