feature: Add method to clear guild user cache (#1767)

* Add method to clear a SocketGuild's user cache

* Add optional predicate

* Compress overload to be consistant

* Fix global user not clearing (may cause other issues)

* Remove debug code and add param documentation

* Standardise doc string

* Remove old hack-fix

* Rename new method for consistency

* Add missing line to reset downloaderPromise

* Undo accidental whitespace changes

* Rider better actually keep the tab this time

Co-authored-by: Quin Lynch <49576606+quinchs@users.noreply.github.com>

src/Discord.Net.WebSocket/ClientState.cs

@@ -115,7 +115,7 @@ namespace Discord.WebSocket
             if (_guilds.TryRemove(id, out SocketGuild guild))
             {
                 guild.PurgeChannelCache(this);
-                guild.PurgeGuildUserCache();
+                guild.PurgeUserCache();
                 return guild;
             }
             return null;
@@ -140,7 +140,7 @@ namespace Discord.WebSocket
         internal void PurgeUsers()
         {
             foreach (var guild in _guilds.Values)
-                guild.PurgeGuildUserCache();
+                guild.PurgeUserCache();
         }
 
         internal SocketApplicationCommand GetCommand(ulong id)

src/Discord.Net.WebSocket/Entities/Guilds/SocketGuild.cs

@@ -1144,22 +1144,29 @@ namespace Discord.WebSocket
             }
             return null;
         }
-        internal void PurgeGuildUserCache()
+
+        /// <summary>
+        ///     Purges this guild's user cache.
+        /// </summary>
+        public void PurgeUserCache() => PurgeUserCache(_ => true);
+        /// <summary>
+        ///     Purges this guild's user cache.
+        /// </summary>
+        /// <param name="predicate">The predicate used to select which users to clear.</param>
+        public void PurgeUserCache(Func<SocketGuildUser, bool> predicate)
         {
-            var members = Users;
-            var self = CurrentUser;
-            _members.Clear();
-            if (self != null)
-                _members.TryAdd(self.Id, self);
+            var membersToPurge = Users.Where(x => predicate.Invoke(x) && x?.Id != Discord.CurrentUser.Id);
+            var membersToKeep = Users.Where(x => !predicate.Invoke(x) || x?.Id == Discord.CurrentUser.Id);
+
+            foreach (var member in membersToPurge)
+                if(_members.TryRemove(member.Id, out _))
+                    member.GlobalUser.RemoveRef(Discord);
+
+            foreach (var member in membersToKeep)
+                _members.TryAdd(member.Id, member);
 
             _downloaderPromise = new TaskCompletionSource<bool>();
             DownloadedMemberCount = _members.Count;
-
-            foreach (var member in members)
-            {
-                if (member.Id != self?.Id)
-                    member.GlobalUser.RemoveRef(Discord);
-            }
         }
 
         /// <summary>