Static class: RT.Serialization.ExactConvert

Assembly: RT.Serialization, Version=1.0.0.9999, Culture=neutral, PublicKeyToken=null
Namespace: RT.Serialization

Summary

Provides functionality similar to Convert, but ensures that all conversions are lossless and roundtrippable. Whenever a conversion cannot be performed exactly, an ExactConvertException is thrown.

Remarks

SUPPORTED TYPES

Supported types are classified as follows. The categories are used in defining
the behaviour of the various conversion types and are vital to understanding what
to expect of the corner cases.

Integer types:
standard - byte, sbyte, short, ushort, int, uint, long, ulong, or any enum type
bool - as integer this is defined exactly as 0 or 1
char - as integer this is the binary value of the char, identical to the "ushort" type
datetime - as integer, this is the number of ticks of the datetime as UTC.
The range is DateTime.MinValue.Ticks ... MaxValue.Ticks.

Fractional types:
single, double
decimal

String type:
string

Unsupported type:
any other type not listed above
null reference (*ALWAYS* behaves exactly the same as if there
was actually an object of an unsupported type)

Definition of terms:
"succeed" / "fail" - these terms do not specify the method by which the outcome of
a conversion is conveyed. This is a separate aspect discussed later.

ExactConvert only allows a conversion to succeed if a roundtrip conversion would result in
at most a very small error. The "very small error" only exists when a Fractional
type is the destination - in this case, ExactConvert picks the nearest
representable value.

A general trait of ExactConvert is that the rules are defined for whole source/destination type
pairs. A necessary exception to this principle is conversion from string, due to the arbitrary
nature of string values.

As a consequence of the above principle, ExactConvert does not allow
Fractional types to be converted to Integer types.

Something to beware of: some of the built-in conversions use national strings for
values, e.g. for True/False/Infinity etc. To avoid any issues like programs crashing
on Spanish computers but not on British ones, the following strings are hard-coded.
All conversions _from_ strings are case-insensitive.

* True
* False
* Inf
* NaN

Static methods

TypeCode	GetTypeCode(object value)	Crutches needed all around... TypeCode.Empty is described as the type code for "a null reference". Unfortunately the only way to retrieve a TypeCode is from a Type object, which can't represent the type of a null reference (well... actually one can't really talk about a _type_ of a _null_ reference in C# at all as far as I understand). Well anyway, wrapping up the rant, this function fills in the spot of a function that's clearly missing: Type.GetTypeCode(object), which returns TypeCode.Empty if asked to get the type of a null object. Something at the back of my mind tells me that there's one way of looking at this where the behaviour of the existing API would make sense... but really, I think this is how it really should have been since it is a lot more useful.
bool	IsIntegerCompatibleType(Type type)	Returns true if the specified type is integer-compatible (in other words, a string of digits can be converted to it using ExactConvert). This includes all types that are ExactConvert.IsTrueIntegerType(Type) as well as DateTime, Char and Boolean.
bool	IsIntegerCompatibleType(TypeCode typeCode)
bool	IsSupportedType(Type type)	Returns true if the specified type is a supported type for converting to other types supported by ExactConvert.
bool	IsSupportedType(TypeCode typeCode)	Returns true if the specified type code is that of a supported type for converting to other types supported by ExactConvert. This does not cover supported objects whose type code is TypeCode.Object.
bool	IsTrueIntegerNullableType(Type type)	Returns true if the specified type is a nullable form of one of the 8 built-in "true" integer types: the signed and unsigned 8, 16, 32 and 64-bit types.
bool	IsTrueIntegerType(Type type)	Returns true if the specified type is one of the 8 built-in "true" integer types: the signed and unsigned 8, 16, 32 and 64-bit types.
bool	IsTrueIntegerType(TypeCode typeCode)
void	To(object value, out bool result)	Converts the specified object to a bool. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out byte result)	Converts the specified object to a byte. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out sbyte result)	Converts the specified object to an sbyte. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out short result)	Converts the specified object to a short. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out ushort result)	Converts the specified object to a ushort. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out int result)	Converts the specified object to an int. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out uint result)	Converts the specified object to a uint. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out long result)	Converts the specified object to a long. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out ulong result)	Converts the specified object to a ulong. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out BigInteger result)
void	To(object value, out float result)	Converts the specified object to a float. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out double result)	Converts the specified object to a double. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out decimal result)	Converts the specified object to a decimal. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out DateTime result)	Converts the specified object to a DateTime. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out char result)	Converts the specified object to a char. Throws an ExactConvertException if the object cannot be converted exactly.
void	To(object value, out string result)	Converts the specified object to a string. Throws an ExactConvertException if the object cannot be converted exactly.
object	To(Type toType, object value)	Converts the value to type toType. Throws an ExactConvertException if the object cannot be converted exactly.
T	To<T>(object value)	Converts the value to type T. Throws an ExactConvertException if the object cannot be converted exactly.
BigInteger	ToBigInteger(object value)	Converts the specified object to a BigInteger. Throws an ExactConvertException if the object cannot be converted exactly.
bool	ToBool(object value)	Converts the specified object to a bool. Throws an ExactConvertException if the object cannot be converted exactly.
byte	ToByte(object value)	Converts the specified object to a byte. Throws an ExactConvertException if the object cannot be converted exactly.
char	ToChar(object value)	Converts the specified object to a char. Throws an ExactConvertException if the object cannot be converted exactly.
DateTime	ToDateTime(object value)	Converts the specified object to a DateTime. Throws an ExactConvertException if the object cannot be converted exactly.
decimal	ToDecimal(object value)	Converts the specified object to a decimal. Throws an ExactConvertException if the object cannot be converted exactly.
double	ToDouble(object value)	Converts the specified object to a double. Throws an ExactConvertException if the object cannot be converted exactly.
float	ToFloat(object value)	Converts the specified object to a float. Throws an ExactConvertException if the object cannot be converted exactly.
int	ToInt(object value)	Converts the specified object to an int. Throws an ExactConvertException if the object cannot be converted exactly.
long	ToLong(object value)	Converts the specified object to a long. Throws an ExactConvertException if the object cannot be converted exactly.
sbyte	ToSByte(object value)	Converts the specified object to an sbyte. Throws an ExactConvertException if the object cannot be converted exactly.
short	ToShort(object value)	Converts the specified object to a short. Throws an ExactConvertException if the object cannot be converted exactly.
string	ToString(object value)	Converts the specified object to a string. Throws an ExactConvertException if the object cannot be converted exactly.
uint	ToUInt(object value)	Converts the specified object to a uint. Throws an ExactConvertException if the object cannot be converted exactly.
ulong	ToULong(object value)	Converts the specified object to a ulong. Throws an ExactConvertException if the object cannot be converted exactly.
ushort	ToUShort(object value)	Converts the specified object to a ushort. Throws an ExactConvertException if the object cannot be converted exactly.
bool	Try(object value, out byte result)	Converts the specified object to a byte. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful.
bool	Try(object value, out ushort result)	Converts the specified object to a ushort. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful.
bool	Try(object value, out uint result)	Converts the specified object to a uint. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful.
bool	Try(object value, out ulong result)	Converts the specified object to a ulong. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful.
bool	Try(object value, out sbyte result)	Converts the specified object to an sbyte. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful.
bool	Try(object value, out short result)	Converts the specified object to a short. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful.
bool	Try(object value, out int result)	Converts the specified object to an int. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful.
bool	Try(object value, out long result)	Converts the specified object to a long. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful.
bool	Try(object value, out BigInteger result)	Converts the specified object to a BigInteger. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful.
bool	Try(object value, out bool result)	Converts the specified object to a bool. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful. If the value is one of the integer types, the exact conversion only succeeds if the value is in range, i.e. 0 or 1. If converting from a string, the string must be exactly (case-insensitive) equal to "True" or "False", or the conversion will fail.
bool	Try(object value, out char result)	Converts the specified object to a char. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful.
bool	Try(object value, out DateTime result)	Converts the specified object to a DateTime. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful. When converting from string, supports a subset of the ISO 8601 formats - for more details see DateTimeExtensions.TryParseIso(string, ref DateTime).
bool	Try(object value, out float result)	Converts the specified object to a float. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful.
bool	Try(object value, out double result)	Converts the specified object to a double. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful.
bool	Try(object value, out decimal result)	Converts the specified object to a decimal. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful.
bool	Try(object value, out string result)	Converts the specified object to a string. Returns true if successful, or false if the object cannot be converted exactly. result is set to the type's default value if the conversion is unsuccessful, which in this case means null (!!!). Note that the result will only ever be false if the value is one of the unsupported types - all supported types can be converted to a string. (So can the unsupported ones but it's a different matter. Unsupported types are not supported by this method for consistency with the other overloads.)
bool	Try(Type toType, object value, out object result)	Converts the specified object to the type toType. Returns true if successful, or false if the object cannot be converted exactly. result is set to null if the conversion is unsuccessful.
long	UnboxIntegerToLong(object integer)	C# does not allow a boxed integer type to be unboxed as anything other than the true type of the boxed integer. This utility function unboxes the integer as the correct type and then casts it to a long, returning the result. Throws an exception if the object is null or not one of the built-in integer types. Does not support unboxing of a ulong because the cast to long would be lossy and misleading. Will throw an exception when given a boxed ulong.
long	UnboxIntegerToLong(object integer, TypeCode typeCode)	A faster version of UnboxIntegerToLong(object) if the TypeCode is already provided. Behaviour is undefined if typeCode does not match the type of the object passed in.

Nested types

ToNullable

Contains static methods to perform an exact conversion to a nullable type. These methods return null only if the input is null. A failed conversion results in an ExactConvertException.