Merge pull request #4333 from Sergio0694/feature/extended-tree-helpers

Feature/extended tree helpers

Author: Sergio0694

Microsoft.Toolkit.Uwp.UI/Enums/SearchType.cs

@@ -0,0 +1,24 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+namespace Microsoft.Toolkit.Uwp.UI
+{
+    /// <summary>
+    /// Indicates a type of search for elements in a visual or logical tree.
+    /// </summary>
+    public enum SearchType
+    {
+        /// <summary>
+        /// Depth-first search, where each branch is recursively explored until the end before moving to the next one.
+        /// </summary>
+        DepthFirst,
+
+        /// <summary>
+        /// Breadth-first search, where each depthwise level is completely explored before moving to the next one.
+        /// This is particularly useful if the target element to find is known to not be too distant from the starting
+        /// point and the whole visual/logical tree from the root is large enough, as it can reduce the traversal time.
+        /// </summary>
+        BreadthFirst
+    }
+}

Microsoft.Toolkit.Uwp.UI/Extensions/DependencyObjectExtensions.cs

@@ -63,7 +63,7 @@ public static partial class FrameworkElementExtensions
         /// </summary>
         /// <typeparam name="T">The type of elements to match.</typeparam>
         /// <param name="element">The root element.</param>
-        /// <param name="predicate">The predicatee to use to match the child nodes.</param>
+        /// <param name="predicate">The predicate to use to match the child nodes.</param>
         /// <returns>The child that was found, or <see langword="null"/>.</returns>
         public static T? FindChild<T>(this FrameworkElement element, Func<T, bool> predicate)
             where T : notnull, FrameworkElement
@@ -80,7 +80,7 @@ public static partial class FrameworkElementExtensions
         /// <typeparam name="TState">The type of state to use when matching nodes.</typeparam>
         /// <param name="element">The root element.</param>
         /// <param name="state">The state to give as input to <paramref name="predicate"/>.</param>
-        /// <param name="predicate">The predicatee to use to match the child nodes.</param>
+        /// <param name="predicate">The predicate to use to match the child nodes.</param>
         /// <returns>The child that was found, or <see langword="null"/>.</returns>
         public static T? FindChild<T, TState>(this FrameworkElement element, TState state, Func<T, TState, bool> predicate)
             where T : notnull, FrameworkElement
@@ -96,7 +96,7 @@ public static partial class FrameworkElementExtensions
         /// <typeparam name="T">The type of elements to match.</typeparam>
         /// <typeparam name="TPredicate">The type of predicate in use.</typeparam>
         /// <param name="element">The root element.</param>
-        /// <param name="predicate">The predicatee to use to match the child nodes.</param>
+        /// <param name="predicate">The predicate to use to match the child nodes.</param>
         /// <returns>The child that was found, or <see langword="null"/>.</returns>
         private static T? FindChild<T, TPredicate>(this FrameworkElement element, ref TPredicate predicate)
             where T : notnull, FrameworkElement
@@ -296,7 +296,7 @@ public static partial class FrameworkElementExtensions
         /// </summary>
         /// <typeparam name="T">The type of elements to match.</typeparam>
         /// <param name="element">The root element.</param>
-        /// <param name="predicate">The predicatee to use to match the child nodes.</param>
+        /// <param name="predicate">The predicate to use to match the child nodes.</param>
         /// <returns>The child (or self) that was found, or <see langword="null"/>.</returns>
         public static T? FindChildOrSelf<T>(this FrameworkElement element, Func<T, bool> predicate)
             where T : notnull, FrameworkElement
@@ -316,7 +316,7 @@ public static partial class FrameworkElementExtensions
         /// <typeparam name="TState">The type of state to use when matching nodes.</typeparam>
         /// <param name="element">The root element.</param>
         /// <param name="state">The state to give as input to <paramref name="predicate"/>.</param>
-        /// <param name="predicate">The predicatee to use to match the child nodes.</param>
+        /// <param name="predicate">The predicate to use to match the child nodes.</param>
         /// <returns>The child (or self) that was found, or <see langword="null"/>.</returns>
         public static T? FindChildOrSelf<T, TState>(this FrameworkElement element, TState state, Func<T, TState, bool> predicate)
             where T : notnull, FrameworkElement
@@ -490,7 +490,7 @@ public static IEnumerable<FrameworkElement> FindChildren(this FrameworkElement e
         /// </summary>
         /// <typeparam name="T">The type of elements to match.</typeparam>
         /// <param name="element">The starting element.</param>
-        /// <param name="predicate">The predicatee to use to match the parent nodes.</param>
+        /// <param name="predicate">The predicate to use to match the parent nodes.</param>
         /// <returns>The parent that was found, or <see langword="null"/>.</returns>
         public static T? FindParent<T>(this FrameworkElement element, Func<T, bool> predicate)
             where T : notnull, FrameworkElement
@@ -507,7 +507,7 @@ public static IEnumerable<FrameworkElement> FindChildren(this FrameworkElement e
         /// <typeparam name="TState">The type of state to use when matching nodes.</typeparam>
         /// <param name="element">The starting element.</param>
         /// <param name="state">The state to give as input to <paramref name="predicate"/>.</param>
-        /// <param name="predicate">The predicatee to use to match the parent nodes.</param>
+        /// <param name="predicate">The predicate to use to match the parent nodes.</param>
         /// <returns>The parent that was found, or <see langword="null"/>.</returns>
         public static T? FindParent<T, TState>(this FrameworkElement element, TState state, Func<T, TState, bool> predicate)
             where T : notnull, FrameworkElement
@@ -523,7 +523,7 @@ public static IEnumerable<FrameworkElement> FindChildren(this FrameworkElement e
         /// <typeparam name="T">The type of elements to match.</typeparam>
         /// <typeparam name="TPredicate">The type of predicate in use.</typeparam>
         /// <param name="element">The starting element.</param>
-        /// <param name="predicate">The predicatee to use to match the parent nodes.</param>
+        /// <param name="predicate">The predicate to use to match the parent nodes.</param>
         /// <returns>The parent that was found, or <see langword="null"/>.</returns>
         private static T? FindParent<T, TPredicate>(this FrameworkElement element, ref TPredicate predicate)
             where T : notnull, FrameworkElement
@@ -600,7 +600,7 @@ public static IEnumerable<FrameworkElement> FindChildren(this FrameworkElement e
         /// </summary>
         /// <typeparam name="T">The type of elements to match.</typeparam>
         /// <param name="element">The starting element.</param>
-        /// <param name="predicate">The predicatee to use to match the parent nodes.</param>
+        /// <param name="predicate">The predicate to use to match the parent nodes.</param>
         /// <returns>The parent (or self) that was found, or <see langword="null"/>.</returns>
         public static T? FindParentOrSelf<T>(this FrameworkElement element, Func<T, bool> predicate)
             where T : notnull, FrameworkElement
@@ -620,7 +620,7 @@ public static IEnumerable<FrameworkElement> FindChildren(this FrameworkElement e
         /// <typeparam name="TState">The type of state to use when matching nodes.</typeparam>
         /// <param name="element">The starting element.</param>
         /// <param name="state">The state to give as input to <paramref name="predicate"/>.</param>
-        /// <param name="predicate">The predicatee to use to match the parent nodes.</param>
+        /// <param name="predicate">The predicate to use to match the parent nodes.</param>
         /// <returns>The parent (or self) that was found, or <see langword="null"/>.</returns>
         public static T? FindParentOrSelf<T, TState>(this FrameworkElement element, TState state, Func<T, TState, bool> predicate)
             where T : notnull, FrameworkElement

Microsoft.Toolkit.Uwp.UI/Extensions/FrameworkElement/FrameworkElementExtensions.LogicalTree.cs

@@ -21,15 +21,15 @@ namespace Microsoft.Toolkit.Uwp.UI.Predicates
         private readonly TState state;
 
         /// <summary>
-        /// The predicatee to use to match items.
+        /// The predicate to use to match items.
         /// </summary>
         private readonly Func<T, TState, bool> predicate;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="PredicateByFunc{T, TState}"/> struct.
         /// </summary>
         /// <param name="state">The state to give as input to <paramref name="predicate"/>.</param>
-        /// <param name="predicate">The predicatee to use to match items.</param>
+        /// <param name="predicate">The predicate to use to match items.</param>
         public PredicateByFunc(TState state, Func<T, TState, bool> predicate)
         {
             this.state = state;

Microsoft.Toolkit.Uwp.UI/Extensions/Predicates/PredicateByFunc{T,TState}.cs

@@ -15,14 +15,14 @@ namespace Microsoft.Toolkit.Uwp.UI.Predicates
         where T : class
     {
         /// <summary>
-        /// The predicatee to use to match items.
+        /// The predicate to use to match items.
         /// </summary>
         private readonly Func<T, bool> predicate;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="PredicateByFunc{T}"/> struct.
         /// </summary>
-        /// <param name="predicate">The predicatee to use to match items.</param>
+        /// <param name="predicate">The predicate to use to match items.</param>
         public PredicateByFunc(Func<T, bool> predicate)
         {
             this.predicate = predicate;

Microsoft.Toolkit.Uwp.UI/Extensions/Predicates/PredicateByFunc{T}.cs

@@ -0,0 +1,129 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Buffers;
+using System.Diagnostics.Contracts;
+using System.Runtime.CompilerServices;
+
+namespace Microsoft.Toolkit.Uwp.UI.Helpers.Internals
+{
+    /// <summary>
+    /// A simple buffer writer implementation using pooled arrays.
+    /// </summary>
+    /// <typeparam name="T">The type of items to store in the list.</typeparam>
+    /// <remarks>
+    /// This type is a <see langword="ref"/> <see langword="struct"/> to avoid the object allocation and to
+    /// enable the pattern-based <see cref="IDisposable"/> support. We aren't worried with consumers not
+    /// using this type correctly since it's private and only accessible within the parent type.
+    /// </remarks>
+    internal struct ArrayPoolBufferWriter<T> : IDisposable
+    {
+        /// <summary>
+        /// The default buffer size to use to expand empty arrays.
+        /// </summary>
+        private const int DefaultInitialBufferSize = 128;
+
+        /// <summary>
+        /// The underlying <typeparamref name="T"/> array.
+        /// </summary>
+        private T[] array;
+
+        /// <summary>
+        /// The starting offset within <see cref="array"/>.
+        /// </summary>
+        private int index;
+
+        /// <summary>
+        /// Creates a new instance of the <see cref="ArrayPoolBufferWriter{T}"/> struct.
+        /// </summary>
+        /// <returns>A new <see cref="ArrayPoolBufferWriter{T}"/> instance.</returns>
+        [Pure]
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static ArrayPoolBufferWriter<T> Create()
+        {
+            return new() { array = ArrayPool<T>.Shared.Rent(DefaultInitialBufferSize) };
+        }
+
+        /// <summary>
+        /// Gets the total number of items stored in the current instance.
+        /// </summary>
+        public int Count
+        {
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            get => this.array.Length;
+        }
+
+        /// <summary>
+        /// Gets the item at the specified offset into the current buffer in use.
+        /// </summary>
+        /// <param name="index">The index of the element to retrieve.</param>
+        /// <returns>The item at the specified offset into the current buffer in use.</returns>
+        /// <exception cref="ArgumentOutOfRangeException">Thrown when <paramref name="index"/> is out of range.</exception>
+        public T this[int index]
+        {
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            get
+            {
+                if ((uint)index >= this.index)
+                {
+                    static void Throw() => throw new ArgumentOutOfRangeException(nameof(index));
+
+                    Throw();
+                }
+
+                return this.array[index];
+            }
+        }
+
+        /// <summary>
+        /// Adds a new item to the current collection.
+        /// </summary>
+        /// <param name="item">The item to add.</param>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public void Add(T item)
+        {
+            if (this.index == this.array.Length)
+            {
+                ResizeBuffer();
+            }
+
+            this.array[this.index++] = item;
+        }
+
+        /// <summary>
+        /// Resets the underlying array and the stored items.
+        /// </summary>
+        public void Reset()
+        {
+            Array.Clear(this.array, 0, this.index);
+
+            this.index = 0;
+        }
+
+        /// <summary>
+        /// Resizes <see cref="array"/> when there is no space left for new items.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        private void ResizeBuffer()
+        {
+            T[] rent = ArrayPool<T>.Shared.Rent(this.index << 2);
+
+            Array.Copy(this.array, 0, rent, 0, this.index);
+            Array.Clear(this.array, 0, this.index);
+
+            ArrayPool<T>.Shared.Return(this.array);
+
+            this.array = rent;
+        }
+
+        /// <inheritdoc cref="IDisposable.Dispose"/>
+        public void Dispose()
+        {
+            Array.Clear(this.array, 0, this.index);
+
+            ArrayPool<T>.Shared.Return(this.array);
+        }
+    }
+}