Merge pull request #232 from MADE-Apps/feature/improvements

Added new extensions and helpers across packages

Author: jamesmcroft

.gitignore

@@ -1,7 +1,7 @@
 ## Ignore Visual Studio temporary files, build results, and
 ## files generated by popular Visual Studio add-ons.
 ##
-## Get latest from https://github.com/github/gitignore/blob/master/VisualStudio.gitignore
+## Get latest from https://github.com/github/gitignore/blob/main/VisualStudio.gitignore
 
 # User-specific files
 *.rsuser
@@ -23,6 +23,7 @@ mono_crash.*
 [Rr]eleases/
 x64/
 x86/
+[Ww][Ii][Nn]32/
 [Aa][Rr][Mm]/
 [Aa][Rr][Mm]64/
 bld/
@@ -61,6 +62,9 @@ project.lock.json
 project.fragment.lock.json
 artifacts/
 
+# ASP.NET Scaffolding
+ScaffoldingReadMe.txt
+
 # StyleCop
 StyleCopReport.xml
 
@@ -86,6 +90,7 @@ StyleCopReport.xml
 *.tmp_proj
 *_wpftmp.csproj
 *.log
+*.tlog
 *.vspscc
 *.vssscc
 .builds
@@ -137,6 +142,11 @@ _TeamCity*
 .axoCover/*
 !.axoCover/settings.json
 
+# Coverlet is a free, cross platform Code Coverage Tool
+coverage*.json
+coverage*.xml
+coverage*.info
+
 # Visual Studio code coverage results
 *.coverage
 *.coveragexml
@@ -284,6 +294,17 @@ node_modules/
 # Visual Studio 6 auto-generated workspace file (contains which files were open etc.)
 *.vbw
 
+# Visual Studio 6 auto-generated project file (contains which files were open etc.)
+*.vbp
+
+# Visual Studio 6 workspace and project file (working project files containing files to include in project)
+*.dsw
+*.dsp
+
+# Visual Studio 6 technical files
+*.ncb
+*.aps
+
 # Visual Studio LightSwitch build output
 **/*.HTMLClient/GeneratedArtifacts
 **/*.DesktopClient/GeneratedArtifacts
@@ -340,6 +361,9 @@ ASALocalRun/
 # Local History for Visual Studio
 .localhistory/
 
+# Visual Studio History (VSHistory) files
+.vshistory/
+
 # BeatPulse healthcheck temp database
 healthchecksdb
 
@@ -348,3 +372,28 @@ MigrationBackup/
 
 # Ionide (cross platform F# VS Code tools) working folder
 .ionide/
+
+# Fody - auto-generated XML schema
+FodyWeavers.xsd
+
+# VS Code files for those working on multiple tools
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+
+# Local History for Visual Studio Code
+.history/
+
+# Windows Installer files from build outputs
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# JetBrains Rider
+*.sln.iml
+.idea/

src/MADE.Collections/CollectionExtensions.cs

@@ -12,6 +12,60 @@ namespace MADE.Collections
     /// </summary>
     public static class CollectionExtensions
     {
+        /// <summary>
+        /// Adds the specified item to the collection based on the specified condition being true.
+        /// </summary>
+        /// <param name="collection">The collection to add the item to.</param>
+        /// <param name="item">The item to add.</param>
+        /// <param name="condition">The condition required to add the item.</param>
+        /// <typeparam name="T">The type of item within the collection.</typeparam>
+        /// <exception cref="ArgumentNullException">Thrown if the <paramref name="collection"/> or <paramref name="condition"/> is <see langword="null"/>.</exception>
+        /// <exception cref="Exception">Potentially thrown by the delegate callback.</exception>
+        public static void AddIf<T>(this IList<T> collection, T item, Func<bool> condition)
+        {
+            if (collection == null)
+            {
+                throw new ArgumentNullException(nameof(collection));
+            }
+
+            if (condition == null)
+            {
+                throw new ArgumentNullException(nameof(condition));
+            }
+
+            if (condition())
+            {
+                collection.Add(item);
+            }
+        }
+
+        /// <summary>
+        /// Removes the specified item from the collection based on the specified condition being true.
+        /// </summary>
+        /// <param name="collection">The collection to remove the item from.</param>
+        /// <param name="item">The item to remove.</param>
+        /// <param name="condition">The condition required to remove the item.</param>
+        /// <typeparam name="T">The type of item within the collection.</typeparam>
+        /// <exception cref="ArgumentNullException">Thrown if the <paramref name="collection"/> or <paramref name="condition"/> is <see langword="null"/>.</exception>
+        /// <exception cref="Exception">Potentially thrown by the delegate callback.</exception>
+        public static void RemoveIf<T>(this IList<T> collection, T item, Func<bool> condition)
+        {
+            if (collection == null)
+            {
+                throw new ArgumentNullException(nameof(collection));
+            }
+
+            if (condition == null)
+            {
+                throw new ArgumentNullException(nameof(condition));
+            }
+
+            if (condition())
+            {
+                collection.Remove(item);
+            }
+        }
+
         /// <summary>
         /// Updates an item within the collection.
         /// </summary>
@@ -114,6 +168,31 @@ public static void AddRange<T>(this ICollection<T> collection, IEnumerable<T> it
             }
         }
 
+        /// <summary>
+        /// Adds the specified collection of items to the collection based on the specified condition being true.
+        /// </summary>
+        /// <param name="collection">The collection to add the items to.</param>
+        /// <param name="itemsToAdd">The items to add.</param>
+        /// <param name="condition">The condition required to add the items.</param>
+        /// <typeparam name="T">The type of item within the collection.</typeparam>
+        /// <exception cref="ArgumentNullException">Thrown if the <paramref name="collection"/>, <paramref name="itemsToAdd"/> or <paramref name="condition"/> is <see langword="null"/>.</exception>
+        /// <exception cref="Exception">Potentially thrown by the delegate callback.</exception>
+        public static void AddRangeIf<T>(
+            this ICollection<T> collection,
+            IEnumerable<T> itemsToAdd,
+            Func<bool> condition)
+        {
+            if (condition == null)
+            {
+                throw new ArgumentNullException(nameof(condition));
+            }
+
+            if (condition())
+            {
+                collection.AddRange(itemsToAdd);
+            }
+        }
+
         /// <summary>
         /// Removes a collection of items from another.
         /// </summary>
@@ -148,6 +227,31 @@ public static void RemoveRange<T>(this ICollection<T> collection, IEnumerable<T>
             }
         }
 
+        /// <summary>
+        /// Removes the specified collection of items from the collection based on the specified condition being true.
+        /// </summary>
+        /// <param name="collection">The collection to remove the items from.</param>
+        /// <param name="itemsToRemove">The items to remove.</param>
+        /// <param name="condition">The condition required to remove the items.</param>
+        /// <typeparam name="T">The type of item within the collection.</typeparam>
+        /// <exception cref="ArgumentNullException">Thrown if the <paramref name="collection"/>, <paramref name="itemsToRemove"/> or <paramref name="condition"/> is <see langword="null"/>.</exception>
+        /// <exception cref="Exception">Potentially thrown by the delegate callback.</exception>
+        public static void RemoveRangeIf<T>(
+            this ICollection<T> collection,
+            IEnumerable<T> itemsToRemove,
+            Func<bool> condition)
+        {
+            if (condition == null)
+            {
+                throw new ArgumentNullException(nameof(condition));
+            }
+
+            if (condition())
+            {
+                collection.RemoveRange(itemsToRemove);
+            }
+        }
+
         /// <summary>
         /// Determines whether two collections are equivalent, containing all the same items with no regard to order.
         /// </summary>
@@ -219,6 +323,7 @@ public static IEnumerable<T> TakeFrom<T>(this List<T> list, int startingIndex, i
         /// <param name="action">
         /// The action to perform.
         /// </param>
+        /// <exception cref="Exception">Potentially thrown by the delegate callback.</exception>
         public static void ForEach<T>(this IEnumerable<T> collection, Action<T> action)
         {
             foreach (T item in collection)
@@ -262,6 +367,7 @@ public static int InsertAtPotentialIndex<T>(this IList<T> source, T value, Func<
         /// <param name="predicate">The action to run to determine the position of the item based on the provided <paramref name="value"/> and an item in the collection.</param>
         /// <typeparam name="T">The type of items in the collection.</typeparam>
         /// <returns>The potential index of the item.</returns>
+        /// <exception cref="Exception">Potentially thrown by the delegate callback.</exception>
         public static int PotentialIndexOf<T>(this IList<T> source, T value, Func<T, T, bool> predicate)
         {
             var result = 0;
@@ -279,5 +385,16 @@ public static int PotentialIndexOf<T>(this IList<T> source, T value, Func<T, T,
 
             return result;
         }
+
+        /// <summary>
+        /// Shuffles the elements of a sequence randomly.
+        /// </summary>
+        /// <param name="source">The collection to shuffle.</param>
+        /// <typeparam name="T">The type of item in the collection.</typeparam>
+        /// <returns>The shuffled collection of items.</returns>
+        public static IEnumerable<T> Shuffle<T>(this IEnumerable<T> source)
+        {
+            return source.OrderBy(x => Guid.NewGuid());
+        }
     }
 }

src/MADE.Collections/ObjectModel/ObservableItemCollection{T}.cs

@@ -27,6 +27,7 @@ public class ObservableItemCollection<T> : ObservableCollection<T>, IDisposable
         /// <summary>
         /// Initializes a new instance of the <see cref="ObservableItemCollection{T}"/> class that is empty and has a default initial capacity.
         /// </summary>
+        /// <exception cref="Exception">Potentially thrown by the <see cref="CollectionChanged"/> callback.</exception>
         public ObservableItemCollection()
         {
             base.CollectionChanged += (s, e) =>
@@ -46,6 +47,7 @@ public ObservableItemCollection()
         /// The collection whose elements are copied to the new list.
         /// </param>
         /// <exception cref="T:System.ArgumentNullException">The <paramref name="collection">collection</paramref> parameter cannot be null.</exception>
+        /// <exception cref="Exception">Potentially thrown by the <see cref="CollectionChanged"/> callback.</exception>
         public ObservableItemCollection(IEnumerable<T> collection)
             : base(collection)
         {
@@ -65,6 +67,7 @@ public ObservableItemCollection(IEnumerable<T> collection)
         /// The list whose elements are copied to the new list.
         /// </param>
         /// <exception cref="T:System.ArgumentNullException">The <paramref name="list">list</paramref> parameter cannot be null.</exception>
+        /// <exception cref="Exception">Potentially thrown by the <see cref="CollectionChanged"/> callback.</exception>
         public ObservableItemCollection(List<T> list)
             : base(list)
         {
@@ -93,6 +96,7 @@ public ObservableItemCollection(List<T> list)
         /// <param name="items">
         /// The objects to add to the end of the collection.
         /// </param>
+        /// <exception cref="Exception">Potentially thrown by the <see cref="CollectionChanged"/> callback.</exception>
         public void AddRange(IEnumerable<T> items)
         {
             this.CheckDisposed();
@@ -117,6 +121,7 @@ public void AddRange(IEnumerable<T> items)
         /// <param name="items">
         /// The objects to remove from the collection.
         /// </param>
+        /// <exception cref="Exception">Potentially thrown by the <see cref="CollectionChanged"/> callback.</exception>
         public void RemoveRange(IEnumerable<T> items)
         {
             this.CheckDisposed();

src/MADE.Data.Converters/BooleanToStringValueConverter.Windows.cs

@@ -80,7 +80,7 @@ public object Convert(object value, Type targetType, object parameter, string la
         /// <returns>The converted <see cref="bool"/> object.</returns>
         public object ConvertBack(object value, Type targetType, object parameter, string language)
         {
-            if (!(value is string b))
+            if (value is not string b)
             {
                 return value;
             }

src/MADE.Data.Converters/Constants/DateTimeConstants.cs

@@ -7,6 +7,11 @@ namespace MADE.Data.Converters.Constants
     /// </summary>
     public static class DateTimeConstants
     {
+        /// <summary>
+        /// Defines the minimum value for a <see cref="DateTime"/> object determined by Unix.
+        /// </summary>
+        public static readonly DateTime UnixEpoch = new(1970, 1, 1, 0, 0, 0);
+
         /// <summary>
         /// Defines the time at the end of a day.
         /// </summary>

src/MADE.Data.Converters/Extensions/DateTimeExtensions.cs

@@ -10,6 +10,30 @@ namespace MADE.Data.Converters.Extensions
     /// </summary>
     public static class DateTimeExtensions
     {
+        /// <summary>
+        /// Gets the day suffix for the specified date, i.e. st, nd, rd, or th.
+        /// </summary>
+        /// <param name="dateTime">The date to get a day suffix for.</param>
+        /// <returns>The day suffix as a string.</returns>
+        public static string ToDaySuffix(this DateTime dateTime)
+        {
+            switch (dateTime.Day)
+            {
+                case 1:
+                case 21:
+                case 31:
+                    return "st";
+                case 2:
+                case 22:
+                    return "nd";
+                case 3:
+                case 23:
+                    return "rd";
+                default:
+                    return "th";
+            }
+        }
+
         /// <summary>
         /// Gets the current age in years based on the specified starting date and today's date.
         /// </summary>
@@ -206,7 +230,7 @@ public static DateTime EndOfYear(this DateTime dateTime)
         /// </returns>
         public static DateTime? SetTime(this DateTime? dateTime, int hours, int minutes, int seconds, int milliseconds)
         {
-            return dateTime == null ? (DateTime?)null : SetTime(dateTime.Value, hours, minutes, seconds, milliseconds);
+            return dateTime == null ? null : SetTime(dateTime.Value, hours, minutes, seconds, milliseconds);
         }
 
         /// <summary>