IFormattable with Union-based Formats

[TheBrambleShark]

Hi all, forgive the awkward title. I wasn't entirely sure what to call this one. This isn't really intended to be any sort of proposal, but it's intended to act as sort of a question and sort of a launching point for a discussion.

One of the oft quoted issues I hear with IFormattable is that it's too widely scoped.

public interface IFormattable
{
    string ToString(string? format, IFormatProvider? formatProvider);
}

format can be anything representable by UTF-8 text. "g", "2", "こんにちは", "yyyyMMdd", or even up to just short of 2gb of Shakespeare's writings could be passed to this method. This presents two problems:

1. Callers of this method have no way to determine what a valid format string is.
   • Humans can read the documentation and, if the documentation is properly implemented, see a list of valid values. But this requires that the maintainer of the type go through the effort to document this.
   • As a bonus 1.a. issue, the method accepts a nullable format string. There is no way to know how the format method would handle a null value, with two possible paths being throwing an exception or coercing the format into a known format such as "G".
2. The method implementation has no way to determine what format string could be passed to it.
   • This is a bit easier, since typically we just use a switch and dump "other" values to an exception or some default.

With .NET 11 just around the corner (RC 1 just released a couple days before the date of writing), this made me think that unions may be able to help solve this issue.

public interface IFormattable<TFormatOptions> where TFormatOptions : IUnion
{
    string ToString(TFormatOptions format, IFormatProvider? formatProvider);
}

This gets us a step closer - now both the caller and implementing method have an exhaustive list of types. However, I feel there are some issues still:

1. It is a little broad. Theoretically, any union determined to be appropriate by the implementer can be used.
2. There is no way to discover a default/general/"G" instance that can be used in situations where there is no desired format.
   • This could be provided in a few ways, like a static abstract DefaultFormat property in IFormattable<TFormatOptions>.
   • We could create an IFormatUnion type that implements IUnion and has the previously mentioned DefaultFormat property.
   • A parameterless ToString() from object is still available, which could forward using ToString(General, null) or similar.
3. format is not permitted to be null, which is by design. If this were allowed to be null, it would reintroduce the same issue as before.

I'm curious to see if anyone has thoughts on restricting this to just IFormatUnions, or if that might be too restricting to developers. Also welcoming general thoughts! If this is something that makes sense to do, I may reformat this into a suggestion, but that's not necessarily a goal of this discussion.

How I imagine this could work.

public union DateTimeFormat(General, ShortDate, LongDate, Custom);

// Static class for organization.
// Union types could also live in the union
public static class DateTimeFormats
{
    public record struct General;
    public record struct ShortDate;
    public record struct LongDate;
    public record struct Custom([StringSyntax(StringSyntaxAttribute.DateTimeFormat)] string format);
}

public readonly struct DateTime : IFormattable<DateTimeFormat>
{
    public string ToString(DateTimeFormat format, IFormatProvider? formatProvider)
    {
        formatProvider ??= CultureInfo.CurrentCulture;
        // snip - formatting body should look pretty similar to existing implementation, but we're matching on type rather than characters.
    }
}

// Sample test
DateTime today = DateTime.Today;
Assert.Equal(today.ToString("G", null), today.ToString(DateTimeFormats.General, null));