Clone this wiki locally
- Supported Backers
- Chaining With
- Explicit Casts
Formatter class provides a way to control exactly what characters are written when serializing a cell of a particular type. Formatters are used in both static and dynamic serialization - in static serialization a
Formatter is specified for an entire column, while in dynamic serialization the
Formatter can vary per-cell.
Formatter instances can be backed by methods and delegates. Both return a
bool value where
true indicates success and
false indicates failure. If a delegate or method fails and a fallback has been configured with
Else(Formatter) the fallback will be tried.
Any delegate of the form
bool Name(FormattingType, in WriteContext, IBufferWriter<char>) can back a
Formatter.ForDelegate<TValue>(FormatterDelegate<TValue>) which conform to this form. You can also explicitly cast any delegate to
Formatter, provided it is logically equivalent to
Concretely, the method must:
- be static
- return a
- have 3 parameters
Formatters can fail, indicated by it's backer returning
false. If Cesil cannot format a value, an exception will be raised.
In order to support this behavior, a failing
Formatter must not write to the
IBufferWriter<char>. Requesting a
Memory<char> does not count as a write,
Advance(int) "commits" to writing. Be aware of helper methods that call
Advance(int) internally, as they may write even in a failure case.
Formatter already has a fallback
Formatter specified, the one passed to
Else(Formatter) will be tried after all the others have failed. Conceptually,
Else(Formatter) adds a
Formatter to the end of a list of fallbacks to try.