added MustBeUnspecified

Author: feO2x

Code/Light.GuardClauses.Performance/DateTimeAssertions/MustBeUnspecifiedBenchmark.cs

@@ -0,0 +1,37 @@
+using System;
+using BenchmarkDotNet.Attributes;
+using Light.GuardClauses.Exceptions;
+
+namespace Light.GuardClauses.Performance.DateTimeAssertions
+{
+    public class MustBeUnspecifiedBenchmark
+    {
+        public DateTime DateTime = new DateTime(2018, 2, 18, 16, 43, 00, DateTimeKind.Unspecified);
+
+        [Benchmark(Baseline = true)]
+        public DateTime ImperativeVersion()
+        {
+            if (DateTime.Kind != DateTimeKind.Unspecified) throw new InvalidDateTimeException(nameof(DateTime));
+            return DateTime;
+        }
+
+        [Benchmark]
+        public DateTime LightGuardClausesParameterName() => DateTime.MustBeUnspecified(nameof(DateTime));
+
+        [Benchmark]
+        public DateTime LightGuardClausesCustomException() => DateTime.MustBeUnspecified(dt => new Exception($"{dt} is not unspecified"));
+
+        [Benchmark]
+        public DateTime OldVersion() => DateTime.OldMustBeUnspecified(nameof(DateTime));
+    }
+
+    public static class MustBeUnspecifiedExtensionMethods
+    {
+        public static DateTime OldMustBeUnspecified(this DateTime dateTime, string parameterName = null, string message = null, Func<Exception> exception = null)
+        {
+            if (dateTime.Kind == DateTimeKind.Unspecified) return dateTime;
+
+            throw exception != null ? exception() : new InvalidDateTimeException(parameterName, message ?? $"The specified date time \"{dateTime:O}\" must be of kind {DateTimeKind.Unspecified}, but actually is {dateTime.Kind}.");
+        }
+    }
+}

Code/Light.GuardClauses.Tests/DateTimeAssertions/MustBeUnspecifiedTests.cs

@@ -0,0 +1,50 @@
+using System;
+using FluentAssertions;
+using Light.GuardClauses.Exceptions;
+using Xunit;
+
+namespace Light.GuardClauses.Tests.DateTimeAssertions
+{
+    public static class MustBeUnspecifiedTests
+    {
+        [Fact]
+        public static void NotUnspecified()
+        {
+            var invalidDateTime = DateTime.UtcNow;
+
+            Action act = () => invalidDateTime.MustBeUnspecified(nameof(invalidDateTime));
+
+            act.Should().Throw<InvalidDateTimeException>()
+               .And.Message.Should().Contain($"{nameof(invalidDateTime)} must use kind \"{DateTimeKind.Unspecified}\", but it actually uses \"{invalidDateTime.Kind}\" and is \"{invalidDateTime:O}\".");
+        }
+
+        [Fact]
+        public static void Unspecified()
+        {
+            var dateTime = DateTime.MinValue;
+
+            var result = dateTime.MustBeUnspecified();
+
+            result.Should().Be(dateTime);
+        }
+
+        [Fact]
+        public static void CustomException() =>
+            Test.CustomException(new DateTime(2018, 2, 18, 16, 57, 00, DateTimeKind.Utc),
+                                 (value, exceptionFactory) => value.MustBeUnspecified(exceptionFactory));
+
+        [Fact]
+        public static void NoCustomException()
+        {
+            var value = new DateTime(2000, 9, 10, 15, 32, 47, DateTimeKind.Unspecified);
+
+            var result = value.MustBeUnspecified(dt => null);
+
+            result.Should().Be(value);
+        }
+
+        [Fact]
+        public static void CustomMessage() =>
+            Test.CustomMessage<InvalidDateTimeException>(message => DateTime.UtcNow.MustBeUnspecified(message: message));
+    }
+}

Code/Light.GuardClauses/Check.DateTimeAssertions.cs

@@ -76,5 +76,39 @@ public static DateTime MustBeLocal(this DateTime parameter, Func<DateTime, Excep
                 Throw.CustomException(exceptionFactory, parameter);
             return parameter;
         }
+
+        /// <summary>
+        /// Ensures that the specified <paramref name="parameter"/> uses <see cref="DateTimeKind.Unspecified"/>, or otherwise throws an <see cref="InvalidDateTimeException"/>.
+        /// </summary>
+        /// <param name="parameter">The date time to be checked.</param>
+        /// <param name="parameterName">The name of the parameter (optional).</param>
+        /// <param name="message">The message that will be passed to the <see cref="InvalidDateTimeException"/> (optional).</param>
+        /// <exception cref="InvalidDateTimeException">Thrown when <paramref name="parameter"/> does not use <see cref="DateTimeKind.Unspecified"/>.</exception>
+#if (NETSTANDARD2_0 || NETSTANDARD1_0 || NET45 || SILVERLIGHT)
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+#endif
+        public static DateTime MustBeUnspecified(this DateTime parameter, string parameterName = null, string message = null)
+        {
+            if (parameter.Kind != DateTimeKind.Unspecified)
+                Throw.MustBeUnspecifiedDateTime(parameter, parameterName, message);
+            return parameter;
+        }
+
+        /// <summary>
+        /// Ensures that the specified <paramref name="parameter"/> uses <see cref="DateTimeKind.Unspecified"/>, or otherwise throws your custom exception.
+        /// </summary>
+        /// <param name="parameter">The date time to be checked.</param>
+        /// <param name="exceptionFactory">The delegate that creates your custom exception. <paramref name="parameter"/> is passed to this delegate.</param>
+        /// <exception cref="Exception">Your custom exception thrown when <paramref name="parameter"/> does not use <see cref="DateTimeKind.Unspecified"/>.</exception>
+#if (NETSTANDARD2_0 || NETSTANDARD1_0 || NET45 || SILVERLIGHT)
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+#endif
+        [ContractAnnotation("exceptionFactory:null => halt")]
+        public static DateTime MustBeUnspecified(this DateTime parameter, Func<DateTime, Exception> exceptionFactory)
+        {
+            if (parameter.Kind != DateTimeKind.Unspecified)
+                Throw.CustomException(exceptionFactory, parameter);
+            return parameter;
+        }
     }
 }

Code/Light.GuardClauses/Exceptions/Throw.cs

@@ -363,6 +363,13 @@ public static void MustBeUtcDateTime(DateTime parameter, string parameterName =
         public static void MustBeLocalDateTime(DateTime parameter, string parameterName = null, string message = null) =>
             throw new InvalidDateTimeException(parameterName, message ?? $"{parameterName ?? "The date time"} must use kind \"{DateTimeKind.Local}\", but it actually uses \"{parameter.Kind}\" and is \"{parameter:O}\".");
 
+        /// <summary>
+        /// Throws the default <see cref="InvalidDateTimeException" /> indicating that a date time is not using <see cref="DateTimeKind.Unspecified" />, using the optional parameter name and message.
+        /// </summary>
+        [ContractAnnotation("=> halt")]
+        public static void MustBeUnspecifiedDateTime(DateTime parameter, string parameterName = null, string message = null) =>
+            throw new InvalidDateTimeException(parameterName, message ?? $"{parameterName ?? "The date time"} must use kind \"{DateTimeKind.Unspecified}\", but it actually uses \"{parameter.Kind}\" and is \"{parameter:O}\".");
+
         /// <summary>
         /// Throws the exception that is returned by <paramref name="exceptionFactory" />.
         /// </summary>