Default Formatters

Default Formatters

• Introduction
• Supported Types
• Additional Details
  • Integer Types
  • float
  • double
  • decimal
  • DateTime
  • DateTimeOffset
  • Guid
  • TimeSpan
  • Uri
  • Nullables
  • Native Integers

Introduction

Cesil has instances of Formatter pre-made for most built-in .NET types. These are used by the Default Type Describer, and can be accessed separately with Formatter.GetDefault(TypeInfo).

Every type that has a default Formatter also has a Default Parser.

Supported Types

• Enums, including [Flags]
• string
• Version
• bool
• char
• DateTime
• DateTimeOffset
• byte
• sbyte
• short
• ushort
• int
• uint
• long
• ulong
• float
• double
• decimal
• Guid
• TimeSpan
• Index
• Range
• Uri
• nint
• nuint

For value types, their Nullable equivalent is also supported.

As a consequence of nint and nuint support, the types IntPtr and UIntPtr are also supported - though use under the latter names is discouraged.

Additional Details

For most built-in types, formatting is either unambiguous (like with string and char) or there's a single TryFormat method to use.

For other types, there are additional decisions that must be made to specify how they're formatted.

Integer Types

Integer types are formatted using the InvariantCulture

float

The float type is formatted using the InvariantCulture and a format string of "G9".

double

The double type is formatted using the InvariantCulture and a format string of "G17".

decimal

The decimal type is formatted using the InvariantCulture.

DateTime

The DateTime type is first converted to UTC with ToUniversalTime, if it is not already in UTC. Formatting a DateTime with a local or unknown DateTimeKind can lead to ambiguous strings.

It is then formatted using the InvariantCulture and a format string of "u".

DateTimeOffset

The DateTimeOffset type is formatted using the InvariantCulture and a format string of "u".

Guid

The Guid type is formatted using a format string of "D".

TimeSpan

The TimeSpan type is formatted using a format string of "c".

Uri

The Uri type is formatted by calling ToString(), which returns a canonical form of the Uri. Accordingly, only the ?, #, and % characters are escaped and the port is elided if it is the default for the Uri's scheme.

Nullables

For any nullable value type, the null value is formatted as the empty string. Likewise, null strings, Versions, and Uris are formatted as the empty string.

Native Integers

The nint and nuint types should be used with care, as the range of valid values differs based on whether code is executing as 32 or 64-bit. Accordingly Cesil may be unable to parse values that were formatted by a process with different bittedness despite have identical declarations in both processes.