Merge branch 'master' into feature/mvvm-toolkit-preview4

Author: michael-hawker

.github/ISSUE_TEMPLATE/bug_report.md

@@ -7,22 +7,25 @@ assignees: ''
 
 ---
 
-<!--
-PLEASE HELP US PROCESS GITHUB ISSUES FASTER BY PROVIDING THE FOLLOWING INFORMATION.
-ISSUES MISSING IMPORTANT INFORMATION MAY BE CLOSED WITHOUT INVESTIGATION.
--->
+<!-- 🚨 Please Do Not skip any instructions and information mentioned below as they are all required and essential to investigate the issue. Issues with missing information may be closed without investigation 🚨 -->
 
 ## Describe the bug
 A clear and concise description of what the bug is.
 
 - [ ] Is this bug a regression in the toolkit?  If so, what toolkit version did you last see it work:
 
 ## Steps to Reproduce
+
+- [ ] Can this be reproduced in the Sample App? (Either in a sample as-is or with new XAML pasted in the editor.) If so, please provide custom XAML or steps to reproduce. If not, let us know why it can't be reproduced (e.g. more complex setup, environment, dependencies, etc...) <!-- Being able to reproduce the problem in the sample app, really stream-lines the whole process in being able to discover, resolve, and validate bug fixes. -->
+
 Steps to reproduce the behavior:
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
+1. Given the following environment (Sample App w/ XAML, Project with Isolated setup, etc...)
+2. Go to '...'
+3. Click on '....'
+4. Scroll down to '....'
+5. See error
+
+<!-- Provide as many code-snippets or XAML snippets where appropriate. -->
 
 ## Expected behavior
 A clear and concise description of what you expected to happen.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -7,6 +7,8 @@ assignees: ''
 
 ---
 
+<!-- 🚨 Please provide detailed information and Do Not skip any instructions as they are all required and essential to help us understand the feature 🚨 -->
+
 ## Describe the problem this feature would solve
 <!-- Please describe or link to any existing issues or discussions.
 A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] -->

.github/ISSUE_TEMPLATE/question.md

@@ -13,6 +13,7 @@ Hi!
 We try and keep our GitHub issue list for bugs and features.
 
 Ideally, it'd be great to post your question on Stack Overflow using the 'windows-community-toolkit' tag here: https://stackoverflow.com/questions/tagged/windows-community-toolkit
+🚨 Please provide detailed information that includes examples, screenshots, and relevant issues if possible 🚨
 
 If this is more about a scenario that you think is missing documentation, please file an issue instead at https://github.com/MicrosoftDocs/WindowsCommunityToolkitDocs/issues/new
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,3 +1,5 @@
+<!-- 🚨 Please Do Not skip any instructions and information mentioned below as they are all required and essential to evaluate and test the PR. By fulfilling all the required information you will be able to reduce the volume of questions and most likely help merge the PR faster 🚨 -->
+
 ## Fixes #
 <!-- Add the relevant issue number after the "#" mentioned above (for ex: Fixes #1234) which will automatically close the issue once the PR is merged. -->
 
@@ -38,7 +40,7 @@ Please check if your PR fulfills the following requirements:
 - [ ] Contains **NO** breaking changes
 
 <!-- If this PR contains a breaking change, please describe the impact and migration path for existing applications below. 
-     Please note that breaking changes are likely to be rejected. -->
+     Please note that breaking changes are likely to be rejected within minor release cycles or held until major versions. -->
 
 
 ## Other information

.gitignore

@@ -227,4 +227,8 @@ msbuild.binlog
 !/build/tools/packages.config
 
 # Generated file from .ttinclude
-**/Generated/TypeInfo.g.cs
+**/Generated/TypeInfo.g.cs
+
+# TAEF Log output
+WexLogFileOutput
+*.wtl

Microsoft.Toolkit.HighPerformance/Extensions/ArrayExtensions.2D.cs

@@ -66,13 +66,13 @@ public static ref T DangerousGetReference<T>(this T[,] array)
         /// </remarks>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static ref T DangerousGetReferenceAt<T>(this T[,] array, int i, int j)
+        public static unsafe ref T DangerousGetReferenceAt<T>(this T[,] array, int i, int j)
         {
 #if NETCORE_RUNTIME
             var arrayData = Unsafe.As<RawArray2DData>(array);
             int offset = (i * arrayData.Width) + j;
             ref T r0 = ref Unsafe.As<byte, T>(ref arrayData.Data);
-            ref T ri = ref Unsafe.Add(ref r0, offset);
+            ref T ri = ref Unsafe.Add(ref r0, (IntPtr)(void*)(uint)offset);
 
             return ref ri;
 #else
@@ -82,10 +82,7 @@ public static ref T DangerousGetReferenceAt<T>(this T[,] array, int i, int j)
                 return ref array[i, j];
             }
 
-            unsafe
-            {
-                return ref Unsafe.AsRef<T>(null);
-            }
+            return ref Unsafe.AsRef<T>(null);
 #endif
         }
 
@@ -274,11 +271,11 @@ public static Span<T> AsSpan<T>(this T[,] array)
         /// <returns>The number of occurrences of <paramref name="value"/> in <paramref name="array"/>.</returns>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static int Count<T>(this T[,] array, T value)
+        public static unsafe int Count<T>(this T[,] array, T value)
             where T : IEquatable<T>
         {
             ref T r0 = ref array.DangerousGetReference();
-            IntPtr length = (IntPtr)array.Length;
+            IntPtr length = (IntPtr)(void*)(uint)array.Length;
 
             return SpanHelper.Count(ref r0, length, value);
         }
@@ -293,11 +290,11 @@ public static int Count<T>(this T[,] array, T value)
         /// <remarks>The Djb2 hash is fully deterministic and with no random components.</remarks>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static int GetDjb2HashCode<T>(this T[,] array)
+        public static unsafe int GetDjb2HashCode<T>(this T[,] array)
             where T : notnull
         {
             ref T r0 = ref array.DangerousGetReference();
-            IntPtr length = (IntPtr)array.Length;
+            IntPtr length = (IntPtr)(void*)(uint)array.Length;
 
             return SpanHelper.GetDjb2HashCode(ref r0, length);
         }

Microsoft.Toolkit.HighPerformance/Extensions/ArrayExtensions.cs

@@ -62,12 +62,12 @@ public static ref T DangerousGetReference<T>(this T[] array)
         /// <remarks>This method doesn't do any bounds checks, therefore it is responsibility of the caller to ensure the <paramref name="i"/> parameter is valid.</remarks>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static ref T DangerousGetReferenceAt<T>(this T[] array, int i)
+        public static unsafe ref T DangerousGetReferenceAt<T>(this T[] array, int i)
         {
 #if NETCORE_RUNTIME
             var arrayData = Unsafe.As<RawArrayData>(array);
             ref T r0 = ref Unsafe.As<byte, T>(ref arrayData.Data);
-            ref T ri = ref Unsafe.Add(ref r0, i);
+            ref T ri = ref Unsafe.Add(ref r0, (IntPtr)(void*)(uint)i);
 
             return ref ri;
 #else
@@ -76,10 +76,7 @@ public static ref T DangerousGetReferenceAt<T>(this T[] array, int i)
                 return ref array[i];
             }
 
-            unsafe
-            {
-                return ref Unsafe.AsRef<T>(null);
-            }
+            return ref Unsafe.AsRef<T>(null);
 #endif
         }
 
@@ -114,11 +111,11 @@ private sealed class RawArrayData
         /// <returns>The number of occurrences of <paramref name="value"/> in <paramref name="array"/>.</returns>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static int Count<T>(this T[] array, T value)
+        public static unsafe int Count<T>(this T[] array, T value)
             where T : IEquatable<T>
         {
             ref T r0 = ref array.DangerousGetReference();
-            IntPtr length = (IntPtr)array.Length;
+            IntPtr length = (IntPtr)(void*)(uint)array.Length;
 
             return SpanHelper.Count(ref r0, length, value);
         }
@@ -185,11 +182,11 @@ public static SpanTokenizer<T> Tokenize<T>(this T[] array, T separator)
         /// <remarks>The Djb2 hash is fully deterministic and with no random components.</remarks>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static int GetDjb2HashCode<T>(this T[] array)
+        public static unsafe int GetDjb2HashCode<T>(this T[] array)
             where T : notnull
         {
             ref T r0 = ref array.DangerousGetReference();
-            IntPtr length = (IntPtr)array.Length;
+            IntPtr length = (IntPtr)(void*)(uint)array.Length;
 
             return SpanHelper.GetDjb2HashCode(ref r0, length);
         }

Microsoft.Toolkit.HighPerformance/Extensions/ReadOnlySpanExtensions.cs

@@ -40,10 +40,40 @@ public static ref T DangerousGetReference<T>(this ReadOnlySpan<T> span)
         /// <remarks>This method doesn't do any bounds checks, therefore it is responsibility of the caller to ensure the <paramref name="i"/> parameter is valid.</remarks>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static ref T DangerousGetReferenceAt<T>(this ReadOnlySpan<T> span, int i)
+        public static unsafe ref T DangerousGetReferenceAt<T>(this ReadOnlySpan<T> span, int i)
         {
+            // Here we assume the input index will never be negative, so we do an unsafe cast to
+            // force the JIT to skip the sign extension when going from int to native int.
+            // On .NET Core 3.1, if we only use Unsafe.Add(ref r0, i), we get the following:
+            // =============================
+            // L0000: mov rax, [rcx]
+            // L0003: movsxd rdx, edx
+            // L0006: lea rax, [rax+rdx*4]
+            // L000a: ret
+            // =============================
+            // Note the movsxd (move with sign extension) to expand the index passed in edx to
+            // the whole rdx register. This is unnecessary and more expensive than just a mov,
+            // which when done to a large register size automatically zeroes the upper bits.
+            // With the (IntPtr)(void*)(uint) cast, we get the following codegen instead:
+            // =============================
+            // L0000: mov rax, [rcx]
+            // L0003: mov edx, edx
+            // L0005: lea rax, [rax+rdx*4]
+            // L0009: ret
+            // =============================
+            // Here we can see how the index is extended to a native integer with just a mov,
+            // which effectively only zeroes the upper bits of the same register used as source.
+            // These three casts are a bit verbose, but they do the trick on both 32 bit and 64
+            // bit architectures, producing optimal code in both cases (they are either completely
+            // elided on 32 bit systems, or result in the correct register expansion when on 64 bit).
+            // We first do an unchecked conversion to uint (which is just a reinterpret-cast). We
+            // then cast to void*, which lets the following IntPtr cast avoid the range check on 32 bit
+            // (since uint could be out of range there if the original index was negative). The final
+            // result is a clean mov as shown above. This will eventually be natively supported by the
+            // JIT compiler (see https://github.com/dotnet/runtime/issues/38794), but doing this here
+            // still ensures the optimal codegen even on existing runtimes (eg. .NET Core 2.1 and 3.1).
             ref T r0 = ref MemoryMarshal.GetReference(span);
-            ref T ri = ref Unsafe.Add(ref r0, i);
+            ref T ri = ref Unsafe.Add(ref r0, (IntPtr)(void*)(uint)i);
 
             return ref ri;
         }
@@ -87,7 +117,7 @@ public static ref T DangerousGetReferenceAt<T>(this ReadOnlySpan<T> span, int i)
         /// </returns>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static ref readonly T DangerousGetLookupReferenceAt<T>(this ReadOnlySpan<T> span, int i)
+        public static unsafe ref readonly T DangerousGetLookupReferenceAt<T>(this ReadOnlySpan<T> span, int i)
         {
             // Check whether the input is in range by first casting both
             // operands to uint and then comparing them, as this allows
@@ -106,12 +136,12 @@ public static ref readonly T DangerousGetLookupReferenceAt<T>(this ReadOnlySpan<
             // lookup table can just be assumed to always be false.
             bool isInRange = (uint)i < (uint)span.Length;
             byte rangeFlag = Unsafe.As<bool, byte>(ref isInRange);
-            int
-                negativeFlag = rangeFlag - 1,
+            uint
+                negativeFlag = unchecked(rangeFlag - 1u),
                 mask = ~negativeFlag,
-                offset = i & mask;
+                offset = (uint)i & mask;
             ref T r0 = ref MemoryMarshal.GetReference(span);
-            ref T r1 = ref Unsafe.Add(ref r0, offset);
+            ref T r1 = ref Unsafe.Add(ref r0, (IntPtr)(void*)offset);
 
             return ref r1;
         }
@@ -165,11 +195,11 @@ public static unsafe int IndexOf<T>(this ReadOnlySpan<T> span, in T value)
         /// <returns>The number of occurrences of <paramref name="value"/> in <paramref name="span"/>.</returns>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static int Count<T>(this ReadOnlySpan<T> span, T value)
+        public static unsafe int Count<T>(this ReadOnlySpan<T> span, T value)
             where T : IEquatable<T>
         {
             ref T r0 = ref MemoryMarshal.GetReference(span);
-            IntPtr length = (IntPtr)span.Length;
+            IntPtr length = (IntPtr)(void*)(uint)span.Length;
 
             return SpanHelper.Count(ref r0, length, value);
         }
@@ -291,11 +321,11 @@ public static ReadOnlySpanTokenizer<T> Tokenize<T>(this ReadOnlySpan<T> span, T
         /// <remarks>The Djb2 hash is fully deterministic and with no random components.</remarks>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static int GetDjb2HashCode<T>(this ReadOnlySpan<T> span)
+        public static unsafe int GetDjb2HashCode<T>(this ReadOnlySpan<T> span)
             where T : notnull
         {
             ref T r0 = ref MemoryMarshal.GetReference(span);
-            IntPtr length = (IntPtr)span.Length;
+            IntPtr length = (IntPtr)(void*)(uint)span.Length;
 
             return SpanHelper.GetDjb2HashCode(ref r0, length);
         }

Microsoft.Toolkit.HighPerformance/Extensions/SpanExtensions.cs

@@ -40,10 +40,10 @@ public static ref T DangerousGetReference<T>(this Span<T> span)
         /// <remarks>This method doesn't do any bounds checks, therefore it is responsibility of the caller to ensure the <paramref name="i"/> parameter is valid.</remarks>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static ref T DangerousGetReferenceAt<T>(this Span<T> span, int i)
+        public static unsafe ref T DangerousGetReferenceAt<T>(this Span<T> span, int i)
         {
             ref T r0 = ref MemoryMarshal.GetReference(span);
-            ref T ri = ref Unsafe.Add(ref r0, i);
+            ref T ri = ref Unsafe.Add(ref r0, (IntPtr)(void*)(uint)i);
 
             return ref ri;
         }
@@ -140,11 +140,11 @@ public static unsafe int IndexOf<T>(this Span<T> span, ref T value)
         /// <returns>The number of occurrences of <paramref name="value"/> in <paramref name="span"/>.</returns>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static int Count<T>(this Span<T> span, T value)
+        public static unsafe int Count<T>(this Span<T> span, T value)
             where T : IEquatable<T>
         {
             ref T r0 = ref MemoryMarshal.GetReference(span);
-            IntPtr length = (IntPtr)span.Length;
+            IntPtr length = (IntPtr)(void*)(uint)span.Length;
 
             return SpanHelper.Count(ref r0, length, value);
         }
@@ -211,11 +211,11 @@ public static SpanTokenizer<T> Tokenize<T>(this Span<T> span, T separator)
         /// <remarks>The Djb2 hash is fully deterministic and with no random components.</remarks>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static int GetDjb2HashCode<T>(this Span<T> span)
+        public static unsafe int GetDjb2HashCode<T>(this Span<T> span)
             where T : notnull
         {
             ref T r0 = ref MemoryMarshal.GetReference(span);
-            IntPtr length = (IntPtr)span.Length;
+            IntPtr length = (IntPtr)(void*)(uint)span.Length;
 
             return SpanHelper.GetDjb2HashCode(ref r0, length);
         }

Microsoft.Toolkit.HighPerformance/Extensions/StringExtensions.cs

@@ -48,7 +48,7 @@ public static ref char DangerousGetReference(this string text)
         /// <remarks>This method doesn't do any bounds checks, therefore it is responsibility of the caller to ensure the <paramref name="i"/> parameter is valid.</remarks>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static ref char DangerousGetReferenceAt(this string text, int i)
+        public static unsafe ref char DangerousGetReferenceAt(this string text, int i)
         {
 #if NETCOREAPP3_1
             ref char r0 = ref Unsafe.AsRef(text.GetPinnableReference());
@@ -57,7 +57,7 @@ public static ref char DangerousGetReferenceAt(this string text, int i)
 #else
             ref char r0 = ref MemoryMarshal.GetReference(text.AsSpan());
 #endif
-            ref char ri = ref Unsafe.Add(ref r0, i);
+            ref char ri = ref Unsafe.Add(ref r0, (IntPtr)(void*)(uint)i);
 
             return ref ri;
         }
@@ -91,10 +91,10 @@ private sealed class RawStringData
         /// <returns>The number of occurrences of <paramref name="c"/> in <paramref name="text"/>.</returns>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static int Count(this string text, char c)
+        public static unsafe int Count(this string text, char c)
         {
             ref char r0 = ref text.DangerousGetReference();
-            IntPtr length = (IntPtr)text.Length;
+            IntPtr length = (IntPtr)(void*)(uint)text.Length;
 
             return SpanHelper.Count(ref r0, length, c);
         }
@@ -157,10 +157,10 @@ public static ReadOnlySpanTokenizer<char> Tokenize(this string text, char separa
         /// <remarks>The Djb2 hash is fully deterministic and with no random components.</remarks>
         [Pure]
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
-        public static int GetDjb2HashCode(this string text)
+        public static unsafe int GetDjb2HashCode(this string text)
         {
             ref char r0 = ref text.DangerousGetReference();
-            IntPtr length = (IntPtr)text.Length;
+            IntPtr length = (IntPtr)(void*)(uint)text.Length;
 
             return SpanHelper.GetDjb2HashCode(ref r0, length);
         }