Include time zone information for Local and Utc DateTimeKind

[russcam]

This commit adds the time zone information for a DateTime within a DateMath type, when the DateTimeKind is Local or Utc. This behaviour aligns 7.x with 6.x.

Introduce StringBuilderCache for caching a StringBuilder per thread. Use of this can be extended in a later commit.

Fixes #3899

[Mpdreamz]

This would be good to have in the codebase going forward.

Need to make sure our usages of Acquire don't overlap before being done with the StringBuilder though

[bkqc]

Isn't all the code in src/Nest/CommonOptions/DateMath/DateMath.cs a big overkill when the format could simply have been changed to .ToString("yyyy-MM-ddTHH:mm:ss.fffffffK") replacing the whole method? Am I missing something?

[russcam]

@bkqc .ToString("yyyy-MM-ddTHH:mm:ss.fffffffK") will always emit 7 sub second fractional values. The behaviour desired in DateMath is to emit the minimal number of sub second fractional values, taking into account a bug in early Elasticsearch 7.x which requires at least 3 sub second fractional values. I suspect that the fix for the bug can be removed in the next major version, simplifying the method.

[bkqc]

Then if we really need to keep the string shorter, can't we get the timezone string in a second call to .ToString(" K").Substring(1) and concatenate after trimming instead of reimplementing the TZ logic?

[russcam]

@bkqc That would be another way to get the timezone, but it's ~12% slower and allocates more

BenchmarkDotNet=v0.12.1, OS=Windows 10.0.19042
Intel Core i7-8850H CPU 2.60GHz (Coffee Lake), 1 CPU, 12 logical and 6 physical cores
.NET Core SDK=5.0.100
  [Host]     : .NET Core 5.0.0 (CoreCLR 5.0.20.51904, CoreFX 5.0.20.51904), X64 RyuJIT
  DefaultJob : .NET Core 5.0.0 (CoreCLR 5.0.20.51904, CoreFX 5.0.20.51904), X64 RyuJIT


|                  Method |     Mean |   Error |   StdDev | Ratio | RatioSD |  Gen 0 | Gen 1 | Gen 2 | Allocated |
|------------------------ |---------:|--------:|---------:|------:|--------:|-------:|------:|------:|----------:|
| ToMinThreeDecimalPlaces | 437.7 ns | 8.31 ns | 14.99 ns |  1.00 |    0.00 | 0.0305 |     - |     - |     144 B |
|               KToString | 494.6 ns | 8.02 ns |  7.11 ns |  1.12 |    0.04 | 0.0420 |     - |     - |     200 B |

Benchmark

using System;
using System.Globalization;
using System.Security.Cryptography;
using System.Text;
using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;

namespace BenchmarkDateTimeToString
{
    class Program
    {
        public static void Main(string[] args)
        {
            var summary = BenchmarkRunner.Run<DateTimeToString>();
        }
    }

    public static class StringBuilderCache
    {
	    private const int DefaultCapacity = 16; // == StringBuilder.DefaultCapacity

	    // The value 360 was chosen in discussion with performance experts as a compromise between using
	    // as little memory per thread as possible and still covering a large part of short-lived
	    // StringBuilder creations on the startup path of VS designers.
	    private const int MaxBuilderSize = 360;

	    // WARNING: We allow diagnostic tools to directly inspect this member (t_cachedInstance).
	    // See https://github.com/dotnet/corert/blob/master/Documentation/design-docs/diagnostics/diagnostics-tools-contract.md for more details.
	    // Please do not change the type, the name, or the semantic usage of this member without understanding the implication for tools.
	    // Get in touch with the diagnostics team if you have questions.
	    [ThreadStatic] private static StringBuilder _cachedInstance;

	    /// <summary>Get a StringBuilder for the specified capacity.</summary>
	    /// <remarks>If a StringBuilder of an appropriate size is cached, it will be returned and the cache emptied.</remarks>
	    public static StringBuilder Acquire(int capacity = DefaultCapacity)
	    {
		    if (capacity <= MaxBuilderSize)
		    {
			    var sb = _cachedInstance;
			    if (sb != null)
			    {
				    // Avoid stringbuilder block fragmentation by getting a new StringBuilder
				    // when the requested size is larger than the current capacity
				    if (capacity <= sb.Capacity)
				    {
					    _cachedInstance = null;
					    sb.Clear();
					    return sb;
				    }
			    }
		    }

		    return new StringBuilder(capacity);
	    }

	    /// <summary>Place the specified builder in the cache if it is not too big.</summary>
	    public static void Release(StringBuilder sb)
	    {
		    if (sb.Capacity <= MaxBuilderSize) _cachedInstance = sb;
	    }

	    /// <summary>ToString() the stringbuilder, Release it to the cache, and return the resulting string.</summary>
	    public static string GetStringAndRelease(StringBuilder sb)
	    {
		    var result = sb.ToString();
		    Release(sb);
		    return result;
	    }
    }

    [MemoryDiagnoser]
    public class DateTimeToString
    {
	    private readonly DateTime DateTime = new DateTime(637134336000010000, DateTimeKind.Utc);

	    [Benchmark(Baseline = true)]
	    public string ToMinThreeDecimalPlaces()
	    {
		    var builder = StringBuilderCache.Acquire(33);
		    var format = DateTime.ToString("yyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFF", CultureInfo.InvariantCulture);
		    builder.Append(format);

		    if (format.Length > 20 && format.Length < 23)
		    {
			    var diff = 23 - format.Length;
			    for (int i = 0; i < diff; i++)
				    builder.Append('0');
		    }

		    switch (DateTime.Kind)
		    {
			    case DateTimeKind.Local:
				    var offset = TimeZoneInfo.Local.GetUtcOffset(DateTime);
				    if (offset >= TimeSpan.Zero)
					    builder.Append('+');
				    else
				    {
					    builder.Append('-');
					    offset = offset.Negate();
				    }

				    AppendTwoDigitNumber(builder, offset.Hours);
				    builder.Append(':');
				    AppendTwoDigitNumber(builder, offset.Minutes);
				    break;
			    case DateTimeKind.Utc:
				    builder.Append('Z');
				    break;
		    }

		    return StringBuilderCache.GetStringAndRelease(builder);
	    }

	    private static void AppendTwoDigitNumber(StringBuilder result, int val)
	    {
		    result.Append((char) ('0' + (val / 10)));
		    result.Append((char) ('0' + (val % 10)));
	    }

	    [Benchmark]
	    public string KToString()
	    {
		    var builder = StringBuilderCache.Acquire(33);
		    var format = DateTime.ToString("yyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFF", CultureInfo.InvariantCulture);
		    builder.Append(format);

		    if (format.Length > 20 && format.Length < 23)
		    {
			    var diff = 23 - format.Length;
			    for (int i = 0; i < diff; i++)
				    builder.Append('0');
		    }

		    builder.Append(DateTime.ToString(" K").Substring(1));
		    return StringBuilderCache.GetStringAndRelease(builder);
	    }
    }
}