Add (Try)GetDateTime(Offset) to Utf8JsonReader and JsonDocument

[ahsonkhan]

We should be consistent regarding what .NET types the Utf8JsonReader, Utf8JsonWriter, and JsonDocument support.

Since there is strong need for adding DateTime support (and the writer allows users to write one), we should add the following APIs to the reader and document.

Add:

public ref partial struct Utf8JsonReader
{
   // These throw InvalidOperationException if there is a token type mismatch (not a string)
   // Throws format exception if the string is not a DateTime (or DateTimeOffset)
   public DateTime GetDateTime();
   public DateTimeOffset GetDateTimeOffset();

   // These throw InvalidOperationException if there is a token type mismatch (not a string)
   public bool TryGetDateTime(out DateTime value);
   public bool TryGetDateTimeOffset(out DateTimeOffset value);
}
public readonly partial struct JsonElement
{
   public DateTime GetDateTime();
   public DateTimeOffset GetDateTimeOffset();

   public bool TryGetDateTime(out DateTime value);
   public bool TryGetDateTimeOffset(out DateTimeOffset value);
}

For consistency, we should remove Write(Guid) from the writer unless a customer requests it. If we want to keep Guid support, add it to the reader/document as well.

Remove:

public ref partial struct Utf8JsonWriter
{
        public void WriteString(System.ReadOnlySpan<byte> utf8PropertyName, System.Guid value, bool escape = true) { }
        public void WriteString(System.ReadOnlySpan<char> propertyName, System.Guid value, bool escape = true) { }
        public void WriteString(string propertyName, System.Guid value, bool escape = true) { }
        public void WriteStringValue(System.Guid value) { }
}

cc @bartonjs, @steveharter, @JamesNK

[JamesNK]

Things to think about:

• Does it parse ISO8061 only or does it support all date formats, ala DateTime.Parse(s)
• If it does support all date formats, what about culture?

[Tornhoof]

we should remove Write(Guid) from the writer unless a customer requests it

Customer here, may I request it?
Examples: Keys in (no)sql databases, which sooner or later show up in storage payload and/or customer payload.

[Tornhoof]

Does it parse ISO8061 only or does it support all date formats, ala DateTime.Parse(s)

Apparently long is still fairly popular, besides ISO8061.
Also make sure it supports parsing different millisecond precisions.

[JamesNK]

I don't think methods for Guid are that important. If Guid then why not TimeSpan, Uri, Version, etc. DateTime/DateTimeOffset are more common, and also I think it is worth offering an opinion about how they are written and read. Dates are a pain point in JSON and an obvious choice stops everyone going out and doing there own thing.

Apparently long is still fairly popular, besides ISO8061.

There is no way to know if an integer is ticks, or seconds since unix epoch.

[Tornhoof]

If Guid then why not TimeSpan

Guid and Timespan are imho better choices, as we already have Utf8Parser/Formatter support. Neither Uri, nor Version have that afaik and need to go through string.

Timespan is as weird as datetime regarding formatting, even with ISO 8601 support, e.g. P1Y2M10DT2H30M (which I don't think many use).

I agree about long, but dto as long was one of the first custom format requests for spanjson, so I listed it here.

[terrajobst]

Video

Looks good.

We should consider applying the same principle from the writer to the reader: the writer differentiates between the underlying primitive and the convenience conversion (e.g. WriteString that takes a DateTime). For example, instead of GetDateTime() we'd have GetStringAsDateTime. That also makes it clear where we expect the value to come from, e.g. GetNumberAsInt32 makes it clear we won't parse the int from a string. And it makes the reader and the writer more consistent.

[layomia]

To start with, the (Try)GetDateTime(Offset) methods will by default parse input strings according to ISO 8061, but ignore CultureInfo and timezone conversion mechanisms. This means the output DateTime(Offset)’s timezone and kind will be the same as the input, if provided.

If the millisecond portion of the input string is provided, fraction digits will be truncated beyond 7 decimal places.

There is an internal DateTime UTF-8 parser that currently only supports a limited ISO 8601 format of "yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'fffffffK". A new parser will be added to support other valid, less restrictive ISO 8601 formats.

[layomia]

(Try)GetDateTime(Offset) and (Try)GetGuid methods have been added to Utf8JsonReader and JsonElement.