Class Formatter

Provides formatting and parsing utilities for converting between different data types with support for culture-specific formatting and null value handling.

Inheritance
System.Object
Formatter
Inherited Members
System.Object.ToString()
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Telerik.WinControls
Assembly: Telerik.WinControls.dll

Syntax

public class Formatter
Remarks

This class offers comprehensive functionality for data binding scenarios where values need to be converted between types while respecting formatting rules and culture settings. Supports nullable types, TypeConverter integration, and special handling for CheckState conversions.

Constructors

Formatter()

Initializes a new instance of the Formatter class.

Declaration
public Formatter()
Remarks

This constructor creates a new Formatter instance. However, most operations are provided as static methods, so instance creation is typically not necessary.

Methods

FormatObject(Object, Type, TypeConverter, TypeConverter, String, IFormatProvider, Object, Object)

Formats the specified value to the target type using comprehensive formatting rules and type conversion.

Declaration
public static object FormatObject(object value, Type targetType, TypeConverter sourceConverter, TypeConverter targetConverter, string formatString, IFormatProvider formatInfo, object formattedNullValue, object dataSourceNullValue)
Parameters
System.Object value

The value to format.
System.Type targetType

The type to format the value to.
System.ComponentModel.TypeConverter sourceConverter

Optional custom TypeConverter for the source type.
System.ComponentModel.TypeConverter targetConverter

Optional custom TypeConverter for the target type.
System.String formatString

Optional format string for IFormattable objects.
System.IFormatProvider formatInfo

Optional format provider for culture-specific formatting.
System.Object formattedNullValue

The value to return when the source value represents null.
System.Object dataSourceNullValue

The value that represents null in the data source.
Returns
System.Object

The formatted value as the target type.
Remarks

Provides comprehensive formatting including null value handling, custom TypeConverter support, format string application for IFormattable objects, and special handling for CheckState conversions.

Exceptions
System.FormatException

Thrown when the formatting operation cannot be completed.

GetDefaultDataSourceNullValue(Type)

Gets the default null value representation for the specified type in data source contexts.

Declaration
public static object GetDefaultDataSourceNullValue(Type type)
Parameters
System.Type type

The type to get the default null value for.
Returns
System.Object

null for reference types; System.DBNull.Value for value types.
Remarks

This method determines the appropriate null value representation based on the type. Reference types use null as their null representation, while value types use System.DBNull.Value since they cannot be assigned null directly.

This is commonly used in data binding scenarios where the data source needs to represent null values in a type-appropriate manner.

Examples
object nullValue1 = Formatter.GetDefaultDataSourceNullValue(typeof(string)); // returns null
object nullValue2 = Formatter.GetDefaultDataSourceNullValue(typeof(int)); // returns DBNull.Value
object nullValue3 = Formatter.GetDefaultDataSourceNullValue(typeof(DateTime)); // returns DBNull.Value

InvokeStringParseMethod(Object, Type, IFormatProvider)

Attempts to invoke a Parse method on the target type to convert a string value to the target type.

Declaration
public static object InvokeStringParseMethod(object value, Type targetType, IFormatProvider formatInfo)
Parameters
System.Object value

The string value to parse.
System.Type targetType

The type to parse the string into.
System.IFormatProvider formatInfo

The format provider for culture-specific parsing.
Returns
System.Object

The parsed value if a suitable Parse method was found and executed successfully; otherwise, a sentinel value indicating that no Parse method was found.
Remarks

Uses reflection to find and invoke Parse methods, searching for Parse(string, NumberStyles, IFormatProvider), Parse(string, IFormatProvider), and Parse(string) in that order of preference.

Exceptions
System.FormatException

Thrown when the Parse method execution fails.

IsNullData(Object, Object)

Determines whether the specified value represents null data based on the data source null value.

Declaration
public static bool IsNullData(object value, object dataSourceNullValue)
Parameters
System.Object value

The value to check for null representation.
System.Object dataSourceNullValue

The value that represents null in the data source context.
Returns
System.Boolean

true if the value represents null data; otherwise, false.
Remarks

This method provides flexible null detection that goes beyond simple null checking. It considers both standard null representations (null and DBNull.Value) and custom null value representations defined by the data source.

This is particularly useful in data binding scenarios where different data sources may use different conventions for representing null or missing values.

Examples
// Standard null checking
bool isNull1 = Formatter.IsNullData(null, DBNull.Value); // returns true
bool isNull2 = Formatter.IsNullData(DBNull.Value, DBNull.Value); // returns true

// Custom null value checking
bool isNull3 = Formatter.IsNullData("", ""); // returns true (empty string as null)
bool isNull4 = Formatter.IsNullData(-1, -1); // returns true (custom sentinel value)

NullData(Type, Object)

Gets the appropriate null data representation for the specified type in data source contexts.

Declaration
public static object NullData(Type type, object dataSourceNullValue)
Parameters
System.Type type

The type to get the null representation for.
System.Object dataSourceNullValue

The data source's null value representation.
Returns
System.Object

null for nullable types when dataSourceNullValue is null or DBNull.Value; otherwise, the dataSourceNullValue for non-nullable types.
Remarks

This method determines the correct null representation based on whether the type is nullable (Nullable<T>) and the data source's null value convention.

For nullable types, null is preferred when the data source uses null or DBNull.Value. For non-nullable types, the data source's null value representation is used.

Examples
// For nullable types
object nullValue1 = Formatter.NullData(typeof(int?), DBNull.Value); // returns null
object nullValue2 = Formatter.NullData(typeof(DateTime?), null); // returns null

// For non-nullable types
object nullValue3 = Formatter.NullData(typeof(int), -1); // returns -1
object nullValue4 = Formatter.NullData(typeof(string), ""); // returns ""

ParseObject(Object, Type, Type, TypeConverter, TypeConverter, IFormatProvider, Object, Object)

Parses the specified value from the source type to the target type using comprehensive parsing rules.

Declaration
public static object ParseObject(object value, Type targetType, Type sourceType, TypeConverter targetConverter, TypeConverter sourceConverter, IFormatProvider formatInfo, object formattedNullValue, object dataSourceNullValue)
Parameters
System.Object value

The value to parse.
System.Type targetType

The type to parse the value to.
System.Type sourceType

The type of the source value.
System.ComponentModel.TypeConverter targetConverter

Optional custom TypeConverter for the target type.
System.ComponentModel.TypeConverter sourceConverter

Optional custom TypeConverter for the source type.
System.IFormatProvider formatInfo

Optional format provider for culture-specific parsing.
System.Object formattedNullValue

The formatted representation of null values.
System.Object dataSourceNullValue

The value that represents null in the data source.
Returns
System.Object

The parsed value as the target type, or the appropriate null representation.
Remarks

Provides comprehensive parsing capabilities including formatted null value detection, custom TypeConverter support, automatic Parse method invocation, and CheckState conversions.

Exceptions
System.FormatException

Thrown when the parsing operation cannot be completed.

Extension Methods