Formatting Overview

The .NET Framework provides a customizable, general-purpose formatting mechanism to convert a value into a string suitable for display. For example, a numeric value can be formatted in hexadecimal, scientific notation, or a series of digits separated into groups with a user-specified punctuation mark. Dates and times can be formatted as appropriate for a particular country, region, or culture. An enumerated constant can be formatted as its numeric value or its name.

You control formatting by specifying a format string and format provider, or by using the defaults. A format string contains one or more format specifier characters that indicate how a value is to be converted. A format provider supplies additional control, replacement, and cultural information required to convert a specific type.

You can override the way the .NET Framework interprets a format string by implementing the IFormattable interface, provide your own format provider by implementing the IFormatProvider interface, and perform your own formatting by implementing the ICustomFormatter interface.

The .NET Framework provides a feature called composite formatting that uses one or more format strings to embed one or more formatted values in a result string. The result string can be used for further processing, displayed to the system console, or written to a stream.

Format Specifiers

The .NET Framework defines standard and custom format specifiers for formatting numbers, dates and times, and enumerations. Format specifiers are used by various methods that format output strings, such as Console.WriteLine and the ToString method of any type, and some methods that parse input strings, such as DateTime.ParseExact.

For information about formatting numeric data, see Numeric Format Strings. For a table of commonly used numeric format specifiers, see Standard Numeric Format Strings, and for a table of custom format specifiers you can use to create your own format string, see Custom Numeric Format Strings.

For information about formatting dates and times, see Date and Time Format Strings. For a table of commonly used date and time format specifiers, see Standard DateTime Format Strings, and for a table of custom date and time format specifiers you can use to create your own format string, see Custom DateTime Format Strings.

For information about formatting enumerations, and a table of standard enumeration format specifiers, see Enumeration Format Strings.

Parsing and Format Specifiers

Formatting converts the value of a type into a string representation; parsing, the inverse of formatting, creates a data type from a string representation. A format provider governs how parsing is performed, and some methods, such as DateTime.ParseExact, take a format specifier parameter that indicates the expected format of the string representation. For more information about parsing, see Parsing Strings.

ToString and Format Specifiers

The .NET Framework supports overloading the default ToString method for a type, which performs rudimentary formatting, with a specialized version of ToString that uses a format specifier parameter to indicate how the value is to be formatted. For more information, see Formatting Base Types and the IFormattable interface.

Format Providers

Format providers supply information such as the character to use as the decimal point when formatting numeric strings, or the separation character to use when formatting a DateTime object. Format providers define the characters used for formatting by the format specifiers, but do not define the specifiers themselves.

A format provider can either be passed to the overload of ToString required by the IFormattable interface, or be predetermined by the method you are using to format text if no format provider is passed.

When no format provider is passed, the information is either inferred, or obtained from one of the standard format providers included in the .NET Framework. Generally, classes that implement IFormattable also provide overloads of ToString that accept only a format specifier or only a format provider. The default ToString method, which accepts no parameters, is inherited from the Object class.

For information about the predefined format provider for numeric data, see NumberFormatInfo. For information about the predefined format provider for dates and times, see DateTimeFormatInfo. For information about creating a custom format provider, or a format provider for a different culture, see CultureInfo and Formatting for Different Cultures.

Composite Formatting

The .NET Framework composite formatting feature, which is supported by methods such as String.Format and the output methods of System.Console and System.IO.TextWriter, replaces each indexed format item embedded in a source string with the formatted equivalent of a corresponding element in a list of values. For more information, see Composite Formatting.

See Also

Formatting Types | Numeric Format Strings | Date and Time Format Strings | Enumeration Format Strings | Customizing Format Strings | Composite Formatting | Parsing Strings | Basic String Operations | IFormattable Interface | IFormatProvider Interface | ICustomFormatter Interface