ClassFormatter
Provides formatting and parsing utilities for converting between different data types with support for culture-specific formatting and null value handling.
Definition
Namespace:Telerik.WinControls
Assembly:Telerik.WinControls.dll
Syntax:
public class FormatterInheritance: objectFormatter
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
value
The value to format.
targetType
The type to format the value to.
sourceConverter
Optional custom TypeConverter for the source type.
targetConverter
Optional custom TypeConverter for the target type.
formatString
Optional format string for IFormattable objects.
formatInfo
Optional format provider for culture-specific formatting.
formattedNullValue
The value to return when the source value represents null.
dataSourceNullValue
The value that represents null in the data source.
Returns
The formatted value as the target type.
Exceptions
Thrown when the formatting operation cannot be completed.
Remarks
Provides comprehensive formatting including null value handling, custom TypeConverter support, format string application for IFormattable objects, and special handling for CheckState conversions.
GetDefaultDataSourceNullValue(Type)
Gets the default null value representation for the specified type in data source contexts.
Declaration
public static object GetDefaultDataSourceNullValue(Type type)Parameters
type
The type to get the default null value for.
Returns
null for reference types; 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 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.
Example
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.ValueInvokeStringParseMethod(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
value
The string value to parse.
targetType
The type to parse the string into.
formatInfo
The format provider for culture-specific parsing.
Returns
The parsed value if a suitable Parse method was found and executed successfully; otherwise, a sentinel value indicating that no Parse method was found.
Exceptions
Thrown when the Parse method execution fails.
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.
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
value
The value to check for null representation.
dataSourceNullValue
The value that represents null in the data source context.
Returns
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.
Example
// 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
type
The type to get the null representation for.
dataSourceNullValue
The data source's null value representation.
Returns
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.
Example
// 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
value
The value to parse.
targetType
The type to parse the value to.
sourceType
The type of the source value.
targetConverter
Optional custom TypeConverter for the target type.
sourceConverter
Optional custom TypeConverter for the source type.
formatInfo
Optional format provider for culture-specific parsing.
formattedNullValue
The formatted representation of null values.
dataSourceNullValue
The value that represents null in the data source.
Returns
The parsed value as the target type, or the appropriate null representation.
Exceptions
Thrown when the parsing operation cannot be completed.
Remarks
Provides comprehensive parsing capabilities including formatted null value detection, custom TypeConverter support, automatic Parse method invocation, and CheckState conversions.