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));

[GeeLaw]

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".

The meaning of null format string is to use the default format. See IFormattable.ToString parameters documentation.

As for

Callers of this method have no way to determine what a valid format string is.

This is a non-issue for the primary use case of IFormattable. This interface is used in string.Format(fmt, objs...) and friends.

• To the string.Format implementation, it doesn't (and doesn't need to / doesn't want to) statically know the object types. It casts objs[i] to IFormattable and passes xyz to it when it sees {i:xyz} in fmt. Since xyz is a substring of fmt, it naturally should be a string?.
• To the caller of string.Format, the caller should know the type of objects being formatted, hence know the allowed format strings. The caller therefore should only pass valid formats in fmt.
• The direct caller of IFormattable.ToString is string.Format, which only serves as a messenger between the "real caller" (the caller of string.Format) and the object. The direct caller hence doesn't care about the validity. It's the real caller's responsibility.

The proposed union-based formattable doesn't serve the aforementioned scenario well:

• There are now an infinite number of formatting interfaces and string.Format won't be able to use a simple cast for proper dispatching. Instead, it will have to use reflection, dig through all interfaces implemented by an object, resolve ambiguity if the object implements more than one construction of the proposed generic interface.
• There's no defined way to convert a substring of fmt to the format union inside string.Format. (Yes, one could introduce additional constraints on the format union, but what for? The original data is string and it's not like that the format union will be reused across multiple calls to string.Format.)

The proposed generic interface can be useful for a completely different formatting mechanism, namely one where the formatting information is supplied as general objects instead of a string.