Guard APIs for .NET Standard 2.1

Microsoft.Toolkit.Parsers/Markdown/Blocks/ListBlock.cs

@@ -11,7 +11,7 @@
 using Microsoft.Toolkit.Parsers.Core;
 using Microsoft.Toolkit.Parsers.Markdown.Helpers;
 
-[assembly: InternalsVisibleTo("UnitTests, PublicKey=002400000480000094000000060200000024000052534131000400000100010041753af735ae6140c9508567666c51c6ab929806adb0d210694b30ab142a060237bc741f9682e7d8d4310364b4bba4ee89cc9d3d5ce7e5583587e8ea44dca09977996582875e71fb54fa7b170798d853d5d8010b07219633bdb761d01ac924da44576d6180cdceae537973982bb461c541541d58417a3794e34f45e6f2d129e2")]
+[assembly: InternalsVisibleTo("UnitTests.UWP, PublicKey=002400000480000094000000060200000024000052534131000400000100010041753af735ae6140c9508567666c51c6ab929806adb0d210694b30ab142a060237bc741f9682e7d8d4310364b4bba4ee89cc9d3d5ce7e5583587e8ea44dca09977996582875e71fb54fa7b170798d853d5d8010b07219633bdb761d01ac924da44576d6180cdceae537973982bb461c541541d58417a3794e34f45e6f2d129e2")]
 
 namespace Microsoft.Toolkit.Parsers.Markdown.Blocks
 {

Microsoft.Toolkit.Uwp.UI.Controls.DataGrid/Properties/AssemblyInfo.cs

@@ -8,5 +8,5 @@
 // General Information about an assembly is controlled through the following
 // set of attributes. Change these attribute values to modify the information
 // associated with an assembly.
-[assembly: InternalsVisibleTo("UnitTests")]
+[assembly: InternalsVisibleTo("UnitTests.UWP")]
 [assembly: NeutralResourcesLanguage("en-US")]

Microsoft.Toolkit.Uwp.UI.Controls/Properties/AssemblyInfo.cs

@@ -8,5 +8,5 @@
 // General Information about an assembly is controlled through the following
 // set of attributes. Change these attribute values to modify the information
 // associated with an assembly.
-[assembly: InternalsVisibleTo("UnitTests")]
+[assembly: InternalsVisibleTo("UnitTests.UWP")]
 [assembly: NeutralResourcesLanguage("en-US")]

Microsoft.Toolkit/Diagnostics/Guard.String.cs

@@ -3,6 +3,9 @@
 // See the LICENSE file in the project root for more information.
 
 using System;
+#if NETSTANDARD2_1
+using System.Diagnostics.CodeAnalysis;
+#endif
 using System.Runtime.CompilerServices;
 
 #nullable enable
@@ -36,7 +39,11 @@ public static void IsNullOrEmpty(string? text, string name)
         /// <param name="name">The name of the input parameter being tested.</param>
         /// <exception cref="ArgumentException">Thrown if <paramref name="text"/> is <see langword="null"/> or empty.</exception>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static void IsNotNullOrEmpty(string? text, string name)
+        public static void IsNotNullOrEmpty(
+#if NETSTANDARD2_1
+            [NotNull]
+#endif
+            string? text, string name)
         {
             if (string.IsNullOrEmpty(text))
             {
@@ -66,7 +73,11 @@ public static void IsNullOrWhitespace(string? text, string name)
         /// <param name="name">The name of the input parameter being tested.</param>
         /// <exception cref="ArgumentException">Thrown if <paramref name="text"/> is <see langword="null"/> or whitespace.</exception>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static void IsNotNullOrWhitespace(string? text, string name)
+        public static void IsNotNullOrWhitespace(
+#if NETSTANDARD2_1
+            [NotNull]
+#endif
+            string? text, string name)
         {
             if (string.IsNullOrWhiteSpace(text))
             {
@@ -229,5 +240,71 @@ public static void HasSizeLessThanOrEqualTo(string text, int size, string name)
                 ThrowHelper.ThrowArgumentExceptionForHasSizeLessThanOrEqualTo(text, size, name);
             }
         }
+
+        /// <summary>
+        /// Asserts that the source <see cref="string"/> instance must have the same size of a destination <see cref="string"/> instance.
+        /// </summary>
+        /// <param name="source">The source <see cref="string"/> instance to check the size for.</param>
+        /// <param name="destination">The destination <see cref="string"/> instance to check the size for.</param>
+        /// <param name="name">The name of the input parameter being tested.</param>
+        /// <exception cref="ArgumentException">Thrown if the size of <paramref name="source"/> is != the one of <paramref name="destination"/>.</exception>
+        /// <remarks>The <see cref="string"/> type is immutable, but the name of this API is kept for consistency with the other overloads.</remarks>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void HasSizeEqualTo(string source, string destination, string name)
+        {
+            if (source.Length != destination.Length)
+            {
+                ThrowHelper.ThrowArgumentExceptionForHasSizeEqualTo(source, destination, name);
+            }
+        }
+
+        /// <summary>
+        /// Asserts that the source <see cref="string"/> instance must have a size of less than or equal to that of a destination <see cref="string"/> instance.
+        /// </summary>
+        /// <param name="source">The source <see cref="string"/> instance to check the size for.</param>
+        /// <param name="destination">The destination <see cref="string"/> instance to check the size for.</param>
+        /// <param name="name">The name of the input parameter being tested.</param>
+        /// <exception cref="ArgumentException">Thrown if the size of <paramref name="source"/> is > the one of <paramref name="destination"/>.</exception>
+        /// <remarks>The <see cref="string"/> type is immutable, but the name of this API is kept for consistency with the other overloads.</remarks>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void HasSizeLessThanOrEqualTo(string source, string destination, string name)
+        {
+            if (source.Length > destination.Length)
+            {
+                ThrowHelper.ThrowArgumentExceptionForHasSizeLessThanOrEqualTo(source, destination, name);
+            }
+        }
+
+        /// <summary>
+        /// Asserts that the input index is valid for a given <see cref="string"/> instance.
+        /// </summary>
+        /// <param name="index">The input index to be used to access <paramref name="text"/>.</param>
+        /// <param name="text">The input <see cref="string"/> instance to use to validate <paramref name="index"/>.</param>
+        /// <param name="name">The name of the input parameter being tested.</param>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown if <paramref name="index"/> is not valid to access <paramref name="text"/>.</exception>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void IsInRangeFor(int index, string text, string name)
+        {
+            if ((uint)index >= (uint)text.Length)
+            {
+                ThrowHelper.ThrowArgumentOutOfRangeExceptionForIsInRangeFor(index, text, name);
+            }
+        }
+
+        /// <summary>
+        /// Asserts that the input index is not valid for a given <see cref="string"/> instance.
+        /// </summary>
+        /// <param name="index">The input index to be used to access <paramref name="text"/>.</param>
+        /// <param name="text">The input <see cref="string"/> instance to use to validate <paramref name="index"/>.</param>
+        /// <param name="name">The name of the input parameter being tested.</param>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown if <paramref name="index"/> is valid to access <paramref name="text"/>.</exception>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static void IsNotInRangeFor(int index, string text, string name)
+        {
+            if ((uint)index < (uint)text.Length)
+            {
+                ThrowHelper.ThrowArgumentOutOfRangeExceptionForIsNotInRangeFor(index, text, name);
+            }
+        }
     }
 }

Microsoft.Toolkit/Diagnostics/Guard.cs

@@ -62,7 +62,22 @@ public static void IsNull<T>(T? value, string name)
         /// <param name="name">The name of the input parameter being tested.</param>
         /// <exception cref="ArgumentNullException">Thrown if <paramref name="value"/> is <see langword="null"/>.</exception>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static void IsNotNull<T>(T? value, string name)
+        [SuppressMessage("StyleCop.CSharp.ReadabilityRules", "SA1114", Justification = "Comment for [NotNull] attribute")]
+        public static void IsNotNull<T>(
+#if NETSTANDARD2_1
+            /* On .NET Standard 2.1, we can add the [NotNull] attribute for
+             * methods that throw if an argument of a nullable type is null.
+             * This will let the compiler know that after a call to such
+             * methods, the value of the variable passed as parameter will
+             * never be null (since if that's the case, the code would have
+             * thrown an exception instead of continuing the execution).
+             * This makes it easy for developers to keep track of the
+             * nullable state of variables, and to avoid having to use
+             * the '!' operator to explicitly ignore compiler warnings
+             * about variables possibly being null. */
+            [NotNull]
+#endif
+            T? value, string name)
             where T : class
         {
             if (value is null)
@@ -80,7 +95,11 @@ public static void IsNotNull<T>(T? value, string name)
         /// <exception cref="ArgumentNullException">Thrown if <paramref name="value"/> is <see langword="null"/>.</exception>
         /// <remarks>The method is generic to avoid boxing the parameters, if they are value types.</remarks>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static void IsNotNull<T>(T? value, string name)
+        public static void IsNotNull<T>(
+#if NETSTANDARD2_1
+            [NotNull]
+#endif
+            T? value, string name)
             where T : struct
         {
             if (value is null)
@@ -262,7 +281,11 @@ public static void IsReferenceNotEqualTo<T>(T value, T target, string name)
         /// <param name="name">The name of the input parameter being tested.</param>
         /// <exception cref="ArgumentException">Thrown if <paramref name="value"/> is <see langword="false"/>.</exception>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static void IsTrue(bool value, string name)
+        public static void IsTrue(
+#if NETSTANDARD2_1
+            [DoesNotReturnIf(false)]
+#endif
+            bool value, string name)
         {
             if (!value)
             {
@@ -277,7 +300,11 @@ public static void IsTrue(bool value, string name)
         /// <param name="name">The name of the input parameter being tested.</param>
         /// <exception cref="ArgumentException">Thrown if <paramref name="value"/> is <see langword="true"/>.</exception>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static void IsFalse(bool value, string name)
+        public static void IsFalse(
+#if NETSTANDARD2_1
+            [DoesNotReturnIf(true)]
+#endif
+            bool value, string name)
         {
             if (value)
             {

Microsoft.Toolkit/Diagnostics/ThrowHelper.String.cs

@@ -89,7 +89,7 @@ public static void ThrowArgumentExceptionForIsNotWhitespace(string text, string
         }
 
         /// <summary>
-        /// Throws an <see cref="ArgumentException"/> when <see cref="Guard.HasSizeEqualTo"/> fails.
+        /// Throws an <see cref="ArgumentException"/> when <see cref="Guard.HasSizeEqualTo(string,int,string)"/> fails.
         /// </summary>
         [MethodImpl(MethodImplOptions.NoInlining)]
         public static void ThrowArgumentExceptionForHasSizeEqualTo(string text, int size, string name)
@@ -134,12 +134,48 @@ public static void ThrowArgumentExceptionForHasSizeLessThan(string text, int siz
         }
 
         /// <summary>
-        /// Throws an <see cref="ArgumentException"/> when <see cref="Guard.HasSizeLessThanOrEqualTo"/> fails.
+        /// Throws an <see cref="ArgumentException"/> when <see cref="Guard.HasSizeLessThanOrEqualTo(string,int,string)"/> fails.
         /// </summary>
         [MethodImpl(MethodImplOptions.NoInlining)]
         public static void ThrowArgumentExceptionForHasSizeLessThanOrEqualTo(string text, int size, string name)
         {
             ThrowArgumentException(name, $"Parameter {name.ToAssertString()} (string) must have a size less than or equal to {size}, had a size of {text.Length} and was {text.ToAssertString()}");
         }
+
+        /// <summary>
+        /// Throws an <see cref="ArgumentException"/> when <see cref="Guard.HasSizeEqualTo(string,string,string)"/> fails.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        public static void ThrowArgumentExceptionForHasSizeEqualTo(string source, string destination, string name)
+        {
+            ThrowArgumentException(name, $"The source {name.ToAssertString()} (string) must have a size equal to {destination.Length.ToAssertString()} (the destination), had a size of {source.Length.ToAssertString()}");
+        }
+
+        /// <summary>
+        /// Throws an <see cref="ArgumentException"/> when <see cref="Guard.HasSizeLessThanOrEqualTo(string,string,string)"/> fails.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        public static void ThrowArgumentExceptionForHasSizeLessThanOrEqualTo(string source, string destination, string name)
+        {
+            ThrowArgumentException(name, $"The source {name.ToAssertString()} (string) must have a size less than or equal to {destination.Length.ToAssertString()} (the destination), had a size of {source.Length.ToAssertString()}");
+        }
+
+        /// <summary>
+        /// Throws an <see cref="ArgumentOutOfRangeException"/> when <see cref="Guard.IsInRangeFor(int,string,string)"/> fails.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        public static void ThrowArgumentOutOfRangeExceptionForIsInRangeFor(int index, string text, string name)
+        {
+            ThrowArgumentOutOfRangeException(name, $"Parameter {name.ToAssertString()} (int) must be in the range given by <0> and {text.Length.ToAssertString()} to be a valid index for the target string, was {index.ToAssertString()}");
+        }
+
+        /// <summary>
+        /// Throws an <see cref="ArgumentOutOfRangeException"/> when <see cref="Guard.IsNotInRangeFor(int,string,string)"/> fails.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        public static void ThrowArgumentOutOfRangeExceptionForIsNotInRangeFor(int index, string text, string name)
+        {
+            ThrowArgumentOutOfRangeException(name, $"Parameter {name.ToAssertString()} (int) must not be in the range given by <0> and {text.Length.ToAssertString()} to be an invalid index for the target string, was {index.ToAssertString()}");
+        }
     }
 }

Microsoft.Toolkit/Microsoft.Toolkit.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>netstandard2.0</TargetFramework>
+    <TargetFrameworks>netstandard2.0;netstandard2.1</TargetFrameworks>
     <LangVersion>8.0</LangVersion>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <Title>Windows Community Toolkit .NET Standard</Title>
@@ -16,10 +16,16 @@
     <DebugType>Full</DebugType>
   </PropertyGroup>
 
-  <ItemGroup>
+  <!-- .NET Standard 2.0 doesn't have the Span<T> type -->
+  <ItemGroup Condition=" '$(TargetFramework)' == 'netstandard2.0' ">
     <PackageReference Include="System.Memory" Version="4.5.3" />
   </ItemGroup>
 
+  <!-- .NET Standard 2.1 doesn't have the Unsafe type -->
+  <ItemGroup Condition=" '$(TargetFramework)' == 'netstandard2.1' ">
+    <PackageReference Include="System.Runtime.CompilerServices.Unsafe" Version="4.7.0" />
+  </ItemGroup>
+
   <ItemGroup>
     <None Update="Diagnostics\Generated\Guard.Comparable.Numeric.tt">
       <Generator>TextTemplatingFileGenerator</Generator>

UnitTests/UnitTests.NetCore/UnitTests.NetCore.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>netcoreapp2.1;netcoreapp3.1</TargetFrameworks>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="16.0.1" />
+    <PackageReference Include="MSTest.TestAdapter" Version="2.1.0" />
+    <PackageReference Include="MSTest.TestFramework" Version="2.1.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\Microsoft.Toolkit\Microsoft.Toolkit.csproj" />
+  </ItemGroup>
+
+  <Import Project="..\UnitTests.Shared\UnitTests.Shared.projitems" Label="Shared" />
+
+</Project>

UnitTests/Diagnostics/Test_Guard.cs → UnitTests/UnitTests.Shared/Diagnostics/Test_Guard.cs

@@ -315,7 +315,7 @@ public void Test_Guard_IsGreaterThan_LowerFalse()
         [TestMethod]
         public void Test_Guard_IsGreaterThanOrEqualTo_Ok()
         {
-            Guard.IsGreaterThanOrEqualTo(2,1, nameof(Test_Guard_IsGreaterThanOrEqualTo_Ok));
+            Guard.IsGreaterThanOrEqualTo(2, 1, nameof(Test_Guard_IsGreaterThanOrEqualTo_Ok));
             Guard.IsGreaterThanOrEqualTo(1, 1, nameof(Test_Guard_IsGreaterThanOrEqualTo_Ok));
             Guard.IsGreaterThanOrEqualTo(MathF.PI, 1, nameof(Test_Guard_IsGreaterThanOrEqualTo_Ok));
             Guard.IsGreaterThanOrEqualTo(MathF.PI, MathF.PI, nameof(Test_Guard_IsGreaterThanOrEqualTo_Ok));

UnitTests/Extensions/Test_ArrayExtensions.cs → UnitTests/UnitTests.Shared/Extensions/Test_ArrayExtensions.cs

@@ -2,11 +2,11 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
-using Microsoft.Toolkit.Extensions;
-using Microsoft.VisualStudio.TestTools.UnitTesting;
 using System;
 using System.Diagnostics;
 using System.Linq;
+using Microsoft.Toolkit.Extensions;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
 
 namespace UnitTests.Extensions
 {
@@ -174,9 +174,9 @@ public void Test_ArrayExtensions_Jagged_GetColumn()
         {
             int[][] array =
             {
-                new int[] { 5, 2, 4 }, 
-                new int[] { 6, 3 }, 
-                new int[] { 7 } 
+                new int[] { 5, 2, 4 },
+                new int[] { 6, 3 },
+                new int[] { 7 }
             };
 
             var col = array.GetColumn(1).ToArray();
@@ -188,7 +188,7 @@ public void Test_ArrayExtensions_Jagged_GetColumn()
         [TestMethod]
         public void Test_ArrayExtensions_Jagged_GetColumn_Exception()
         {
-            int[][] array = 
+            int[][] array =
             {
                 new int[] { 5, 2, 4 },
                 new int[] { 6, 3 },

UnitTests/UnitTests.Shared/UnitTests.Shared.projitems

@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <PropertyGroup>
+    <MSBuildAllProjects>$(MSBuildAllProjects);$(MSBuildThisFileFullPath)</MSBuildAllProjects>
+    <HasSharedItems>true</HasSharedItems>
+    <SharedGUID>4e9466d1-d5aa-46ac-801b-c8fdab79f0d4</SharedGUID>
+  </PropertyGroup>
+  <PropertyGroup Label="Configuration">
+    <Import_RootNamespace>UnitTests.Shared</Import_RootNamespace>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="$(MSBuildThisFileDirectory)Diagnostics\Test_Guard.Array.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Diagnostics\Test_Guard.Comparable.Numeric.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Diagnostics\Test_Guard.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Extensions\Test_ArrayExtensions.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Extensions\Test_TypeExtensions.cs" />
+    <Compile Include="$(MSBuildThisFileDirectory)Extensions\Test_ValueTypeExtensions.cs" />
+  </ItemGroup>
+</Project>