Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Format Method
Collapse the table of content
Expand the table of content

ICustomFormatter::Format Method

Converts the value of a specified object to an equivalent string representation using specified format and culture-specific formatting information.

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

String^ Format(
	String^ format, 
	Object^ arg, 
	IFormatProvider^ formatProvider
)

Parameters

format
Type: System::String

A format string containing formatting specifications.

arg
Type: System::Object

An object to format.

formatProvider
Type: System::IFormatProvider

An object that supplies format information about the current instance.

Return Value

Type: System::String
The string representation of the value of arg, formatted as specified by format and formatProvider.

ICustomFormatter::Format is a callback method. It is called by a method that supports custom formatting, such as String::Format(IFormatProvider, String, array<Object>) or StringBuilder::AppendFormat(IFormatProvider, String, array<Object>). The implementation is called once for each format item in a composite format string. For example, in the following statement, the ICustomFormatter::Format method is called three times.

No code example is currently available or this language may not be supported.

The arg parameter is the object in the object list whose zero-based position corresponds to the index of a particular format item.

The format parameter contains a format string, which is the formatString component of a format item. If the format item has no formatString component, the value of format is nullptr. If format is nullptr, depending on the type of arg, you may be able to use the default format specification of your choice.

The formatProvider parameter is the IFormatProvider implementation that provides formatting for arg. Typically, it is an instance of your ICustomFormatter implementation. If formatProvider is nullptr, ignore that parameter.

Your implementation of the Format method must include the following functionality so the .NET Framework can provide formatting you do not support. If your format method does not support a format, determine whether the object being formatted implements the IFormattable interface. If it does, invoke the IFormattable::ToString method of that interface. Otherwise, invoke the default Object::ToString method of the underlying object. The following code illustrates this pattern.

No code example is currently available or this language may not be supported.

The following example implements ICustomFormatter to allow binary, octal, and hexadecimal formatting of integral values. Its ICustomFormatter::Format implementation determines whether the format parameter is one of the three supported format strings ("B" for binary, "O" for octal, and "H" for hexadecimal) and formats the arg parameter appropriately. Otherwise, if arg is not nullptr, it calls the arg parameter's IFormattable::ToString implementation, if one exists, or its parameterless ToString method, if one does not. If arg is nullptr, the method returns String::Empty.

No code example is currently available or this language may not be supported.

BinaryFormatter can then be used to provide custom formatting by passing a BinaryFormatter object as the provider parameter of the Format method, as the following example shows.

No code example is currently available or this language may not be supported.

.NET Framework

Supported in: 4.6, 4.5, 4, 3.5, 3.0, 2.0, 1.1

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

XNA Framework

Supported in: 3.0, 2.0, 1.0

.NET for Windows Phone apps

Supported in: Windows Phone 8.1, Windows Phone Silverlight 8.1, Windows Phone Silverlight 8

Portable Class Library

Supported in: Portable Class Library
Show:
© 2015 Microsoft