NumberFormatInfo Class

Defines how numeric values are formatted and displayed, depending on the culture.

Namespace: System.Globalization
Assembly: mscorlib (in mscorlib.dll)

public sealed class NumberFormatInfo : ICloneable, IFormatProvider
/** @attribute SerializableAttribute() */ 
/** @attribute ComVisibleAttribute(true) */ 
public final class NumberFormatInfo implements ICloneable, IFormatProvider
public final class NumberFormatInfo implements ICloneable, IFormatProvider
Not applicable.

This class contains information, such as currency, decimal separators, and other numeric symbols.

To create a NumberFormatInfo object for a specific culture, your application creates a CultureInfo object for that culture and retrieves the CultureInfo.NumberFormat property. To create a NumberFormatInfo object for the culture of the current thread, the application uses the CurrentInfo property. To create a NumberFormatInfo object for the invariant culture, the application uses the InvariantInfo property for a read-only version, or uses the NumberFormatInfo constructor for a writable version. It is not possible to create a NumberFormatInfo object for a neutral culture.

The user might choose to override some of the values associated with the current culture of Windows through the regional and language options in Control Panel. For example, the user might choose to display the date in a different format or to use a currency other than the default for the culture. If the CultureInfo.UseUserOverride property is set to true, the properties CultureInfo.DateTimeFormat, CultureInfo.NumberFormat, and CultureInfo.TextInfo are also retrieved from the user settings. If the user settings are incompatible with the culture associated with the CultureInfo object, for example, if the selected calendar is not one of the OptionalCalendars, the results of the methods and the values of the properties are undefined.

For versions of .NET Framework prior to 2.0, if the application sets the CultureInfo.UseUserOverride property to true, the object reads each user-overridable property only when it is accessed for the first time. Because NumberFormatInfo has more than one user-overridable property, this "lazy initialization" can lead to an inconsistency between such properties when the application accesses one property, the user changes to another culture or overrides properties of the current user culture through regional and language options in Control Panel, then the application accesses a different property. For example, in a sequence like this, CurrencyGroupSeparator can be accessed. Then the user can change patterns in the Control Panel, and CurrencyDecimalSeparator, when accessed, follows the new settings. A similar inconsistency occurs when the user changes the user culture in the Control Panel.

In .NET Framework version 2.0 and later, NumberFormatInfo does not use this "lazy initialization." Instead, it reads all user-overridable properties when it is created. There is still a small window of vulnerability in which neither object creation nor the user override process is atomic, and the relevant values can change during object creation. However, the occurrence of this vulnerability is extremely rare.

Numeric values are formatted using standard or custom patterns stored in the properties of a NumberFormatInfo. To modify the display of a value, the application must make the NumberFormatInfo object writable so that custom patterns can be saved in its properties.

The following table describes the standard format patterns for each standard format specifier and the associated NumberFormatInfo properties that can be set to modify the standard formats.

Format pattern

Description and Associated Properties

c, C

Currency format. Associated properties are:

CurrencyNegativePattern, CurrencyPositivePattern, CurrencySymbol, CurrencyGroupSizes, CurrencyGroupSeparator, CurrencyDecimalDigits, CurrencyDecimalSeparator.

d, D

Decimal format.

e, E

Scientific (exponential) format.

f, F

Fixed-point format.

g, G

General format.

n, N

Number format. Associated properties are:

NumberNegativePattern, NumberGroupSizes, NumberGroupSeparator, NumberDecimalDigits, NumberDecimalSeparator.

p, P

Percent format. Use of this format converts a number to a string that represents a percent. The string is defined by the PercentPositivePattern property if the number is positive. The string is defined by the PercentNegativePattern property and starts with a minus sign if the number is negative. The converted number is multiplied by 100 for presentation as a percentage. A precision specifier indicating the desired number of decimal places, for example, "{0:p6}", is allowed. If the precision specifier is omitted, the default numeric precision supported by NumberFormatInfo is used.

r, R

Round-trip format. Use of this format ensures that a floating-point numeric value converted to a string has the same value when the string is converted back to a numeric value. This format is supported only for the single and double types. When a numeric value is formatted using this format pattern, it is first tested using the general format, with 15 digits of precision for a double type and 7 digits of precision for a single type. If the value is successfully parsed back to the same numeric value, it is formatted using the general format specifier. However, if the value is not successfully parsed back to the same numeric value, the value is formatted using 17 digits of precision for a double type and 9 digits of precision for a single type.

A precision specifier can be appended to the round-trip format pattern, but it is ignored. Round trips are given precedence over precision when using this format pattern.

x, X

Hexadecimal format.

For details about the use of these patterns, see Standard Numeric Format Strings and Custom Numeric Format Strings.

A NumberFormatInfo object can be created only for the invariant culture or for specific cultures, not for neutral cultures. For more information about the invariant culture, specific cultures, and neutral cultures, see the CultureInfo class.

NumberFormatInfo implements the ICloneable interface to enable duplication of NumberFormatInfo objects. It also implements IFormatProvider to supply formatting information to applications.

The following code example shows how to retrieve a NumberFormatInfo object for a corresponding CultureInfo object, and use the retrieved object to query number formatting information for the particular culture.

using System;
using System.Globalization;
using System.Text;

public sealed class App 
    static void Main() 
        StringBuilder sb = new StringBuilder();

        // Loop through all the specific cultures known to the CLR.
        foreach (CultureInfo ci in CultureInfo.GetCultures(CultureTypes.SpecificCultures)) 
            // Only show the currency symbols for cultures that speak English.
            if (ci.TwoLetterISOLanguageName != "en") continue;
            // Display the culture name and currency symbol.
            NumberFormatInfo nfi = ci.NumberFormat;
            sb.AppendFormat("The currency symbol for '{0}' is '{1}'",
                ci.DisplayName, nfi.CurrencySymbol);

// This code produces the following output.
// The currency symbol for 'English (United States)' is '$'
// The currency symbol for 'English (United Kingdom)' is ''
// The currency symbol for 'English (Australia)' is '$'
// The currency symbol for 'English (Canada)' is '$'
// The currency symbol for 'English (New Zealand)' is '$'
// The currency symbol for 'English (Ireland)' is '?'
// The currency symbol for 'English (South Africa)' is 'R'
// The currency symbol for 'English (Jamaica)' is 'J$'
// The currency symbol for 'English (Caribbean)' is '$'
// The currency symbol for 'English (Belize)' is 'BZ$'
// The currency symbol for 'English (Trinidad and Tobago)' is 'TT$'
// The currency symbol for 'English (Zimbabwe)' is 'Z$'
// The currency symbol for 'English (Republic of the Philippines)' is 'Php'


Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Windows 98, Windows Server 2000 SP4, Windows CE, Windows Millennium Edition, Windows Mobile for Pocket PC, Windows Mobile for Smartphone, Windows Server 2003, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP SP2, Windows XP Starter Edition

The Microsoft .NET Framework 3.0 is supported on Windows Vista, Microsoft Windows XP SP2, and Windows Server 2003 SP1.

.NET Framework

Supported in: 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 2.0, 1.0

XNA Framework

Supported in: 1.0