Add Invoke and InvokeIf overloads to FluentExtensions

CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### New features
 
+- Added overloads of `Louis.Fluency.FluentExtensions.Invoke` that allow for additional arguments to be passed to lambdas to avoid the allocation of closure objects.
+- Added method `Louis.Fluency.FluentExtensions.InvokeIf` that calls the provided action only if a condition is `true`.
+
 ### Changes to existing features
 
 ### Bugs fixed in this release

src/Louis/Fluency/FluentExtensions-Invoke.cs

@@ -28,4 +28,108 @@ public static T Invoke<T>(this T @this, Action<T> action)
         action(@this);
         return @this;
     }
+
+    /// <summary>
+    /// Invokes an action on an object and an additional argument and returns the same object.
+    /// </summary>
+    /// <typeparam name="T">The type of the object.</typeparam>
+    /// <typeparam name="TArg">The type of the additional parameter to <paramref name="action"/>.</typeparam>
+    /// <param name="this">The object on which this method was called.</param>
+    /// <param name="arg">The additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="action">The action to perform on <paramref name="this"/> and <paramref name="arg"/>.</param>
+    /// <returns>A reference to <paramref name="this"/> after <paramref name="action"/> returns.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// <para><paramref name="this"/> is <see langword="null"/>.</para>
+    /// <para>- or -</para>
+    /// <para><paramref name="action"/> is <see langword="null"/>.</para>
+    /// </exception>
+    public static T Invoke<T, TArg>(this T @this, TArg arg, Action<T, TArg> action)
+    {
+        Guard.IsNotNull(@this);
+        Guard.IsNotNull(action);
+
+        action(@this, arg);
+        return @this;
+    }
+
+    /// <summary>
+    /// Invokes an action on an object and additional arguments and returns the same object.
+    /// </summary>
+    /// <typeparam name="T">The type of the object.</typeparam>
+    /// <typeparam name="TArg1">The type of the first additional parameter to <paramref name="action"/>.</typeparam>
+    /// <typeparam name="TArg2">The type of the second additional parameter to <paramref name="action"/>.</typeparam>
+    /// <param name="this">The object on which this method was called.</param>
+    /// <param name="arg1">The First additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="arg2">The second additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="action">The action to perform on <paramref name="this"/> and the additional arguments.</param>
+    /// <returns>A reference to <paramref name="this"/> after <paramref name="action"/> returns.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// <para><paramref name="this"/> is <see langword="null"/>.</para>
+    /// <para>- or -</para>
+    /// <para><paramref name="action"/> is <see langword="null"/>.</para>
+    /// </exception>
+    public static T Invoke<T, TArg1, TArg2>(this T @this, TArg1 arg1, TArg2 arg2, Action<T, TArg1, TArg2> action)
+    {
+        Guard.IsNotNull(@this);
+        Guard.IsNotNull(action);
+
+        action(@this, arg1, arg2);
+        return @this;
+    }
+
+    /// <summary>
+    /// Invokes an action on an object and additional arguments and returns the same object.
+    /// </summary>
+    /// <typeparam name="T">The type of the object.</typeparam>
+    /// <typeparam name="TArg1">The type of the first additional parameter to <paramref name="action"/>.</typeparam>
+    /// <typeparam name="TArg2">The type of the second additional parameter to <paramref name="action"/>.</typeparam>
+    /// <typeparam name="TArg3">The type of the third additional parameter to <paramref name="action"/>.</typeparam>
+    /// <param name="this">The object on which this method was called.</param>
+    /// <param name="arg1">The First additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="arg2">The second additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="arg3">The third additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="action">The action to perform on <paramref name="this"/> and the additional arguments.</param>
+    /// <returns>A reference to <paramref name="this"/> after <paramref name="action"/> returns.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// <para><paramref name="this"/> is <see langword="null"/>.</para>
+    /// <para>- or -</para>
+    /// <para><paramref name="action"/> is <see langword="null"/>.</para>
+    /// </exception>
+    public static T Invoke<T, TArg1, TArg2, TArg3>(this T @this, TArg1 arg1, TArg2 arg2, TArg3 arg3, Action<T, TArg1, TArg2, TArg3> action)
+    {
+        Guard.IsNotNull(@this);
+        Guard.IsNotNull(action);
+
+        action(@this, arg1, arg2, arg3);
+        return @this;
+    }
+
+    /// <summary>
+    /// Invokes an action on an object and additional arguments and returns the same object.
+    /// </summary>
+    /// <typeparam name="T">The type of the object.</typeparam>
+    /// <typeparam name="TArg1">The type of the first additional parameter to <paramref name="action"/>.</typeparam>
+    /// <typeparam name="TArg2">The type of the second additional parameter to <paramref name="action"/>.</typeparam>
+    /// <typeparam name="TArg3">The type of the third additional parameter to <paramref name="action"/>.</typeparam>
+    /// <typeparam name="TArg4">The type of the fourth additional parameter to <paramref name="action"/>.</typeparam>
+    /// <param name="this">The object on which this method was called.</param>
+    /// <param name="arg1">The First additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="arg2">The second additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="arg3">The third additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="arg4">The fourth additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="action">The action to perform on <paramref name="this"/> and the additional arguments.</param>
+    /// <returns>A reference to <paramref name="this"/> after <paramref name="action"/> returns.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// <para><paramref name="this"/> is <see langword="null"/>.</para>
+    /// <para>- or -</para>
+    /// <para><paramref name="action"/> is <see langword="null"/>.</para>
+    /// </exception>
+    public static T Invoke<T, TArg1, TArg2, TArg3, TArg4>(this T @this, TArg1 arg1, TArg2 arg2, TArg3 arg3, TArg4 arg4, Action<T, TArg1, TArg2, TArg3, TArg4> action)
+    {
+        Guard.IsNotNull(@this);
+        Guard.IsNotNull(action);
+
+        action(@this, arg1, arg2, arg3, arg4);
+        return @this;
+    }
 }

src/Louis/Fluency/FluentExtensions-InvokeIf.cs

@@ -0,0 +1,160 @@
+// Copyright (c) Tenacom and contributors. Licensed under the MIT license.
+// See the LICENSE file in the project root for full license information.
+
+using System;
+using CommunityToolkit.Diagnostics;
+
+namespace Louis.Fluency;
+
+partial class FluentExtensions
+{
+    /// <summary>
+    /// Invokes an action on an object if a condition if satisfied, then returns the same object.
+    /// </summary>
+    /// <typeparam name="T">The type of the object.</typeparam>
+    /// <param name="this">The object on which this method was called.</param>
+    /// <param name="condition">The condition to check.</param>
+    /// <param name="action">The action to perform on <paramref name="this"/>.</param>
+    /// <returns>A reference to <paramref name="this"/> after <paramref name="action"/> returns.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// <para><paramref name="this"/> is <see langword="null"/>.</para>
+    /// <para>- or -</para>
+    /// <para><paramref name="action"/> is <see langword="null"/>.</para>
+    /// </exception>
+    public static T InvokeIf<T>(this T @this, bool condition, Action<T> action)
+    {
+        Guard.IsNotNull(@this);
+        Guard.IsNotNull(action);
+
+        if (condition)
+        {
+            action(@this);
+        }
+
+        return @this;
+    }
+
+    /// <summary>
+    /// Invokes an action on an object and an additional argument if a condition if satisfied, then returns the same object.
+    /// </summary>
+    /// <typeparam name="T">The type of the object.</typeparam>
+    /// <typeparam name="TArg">The type of the additional parameter to <paramref name="action"/>.</typeparam>
+    /// <param name="this">The object on which this method was called.</param>
+    /// <param name="condition">The condition to check.</param>
+    /// <param name="arg">The additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="action">The action to perform on <paramref name="this"/> and <paramref name="arg"/>.</param>
+    /// <returns>A reference to <paramref name="this"/> after <paramref name="action"/> returns.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// <para><paramref name="this"/> is <see langword="null"/>.</para>
+    /// <para>- or -</para>
+    /// <para><paramref name="action"/> is <see langword="null"/>.</para>
+    /// </exception>
+    public static T InvokeIf<T, TArg>(this T @this, bool condition, TArg arg, Action<T, TArg> action)
+    {
+        Guard.IsNotNull(@this);
+        Guard.IsNotNull(action);
+
+        if (condition)
+        {
+            action(@this, arg);
+        }
+
+        return @this;
+    }
+
+    /// <summary>
+    /// Invokes an action on an object and additional arguments if a condition if satisfied, then returns the same object.
+    /// </summary>
+    /// <typeparam name="T">The type of the object.</typeparam>
+    /// <typeparam name="TArg1">The type of the first additional parameter to <paramref name="action"/>.</typeparam>
+    /// <typeparam name="TArg2">The type of the second additional parameter to <paramref name="action"/>.</typeparam>
+    /// <param name="this">The object on which this method was called.</param>
+    /// <param name="condition">The condition to check.</param>
+    /// <param name="arg1">The First additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="arg2">The second additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="action">The action to perform on <paramref name="this"/> and the additional arguments.</param>
+    /// <returns>A reference to <paramref name="this"/> after <paramref name="action"/> returns.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// <para><paramref name="this"/> is <see langword="null"/>.</para>
+    /// <para>- or -</para>
+    /// <para><paramref name="action"/> is <see langword="null"/>.</para>
+    /// </exception>
+    public static T InvokeIf<T, TArg1, TArg2>(this T @this, bool condition, TArg1 arg1, TArg2 arg2, Action<T, TArg1, TArg2> action)
+    {
+        Guard.IsNotNull(@this);
+        Guard.IsNotNull(action);
+
+        if (condition)
+        {
+            action(@this, arg1, arg2);
+        }
+
+        return @this;
+    }
+
+    /// <summary>
+    /// Invokes an action on an object and additional arguments if a condition if satisfied, then returns the same object.
+    /// </summary>
+    /// <typeparam name="T">The type of the object.</typeparam>
+    /// <typeparam name="TArg1">The type of the first additional parameter to <paramref name="action"/>.</typeparam>
+    /// <typeparam name="TArg2">The type of the second additional parameter to <paramref name="action"/>.</typeparam>
+    /// <typeparam name="TArg3">The type of the third additional parameter to <paramref name="action"/>.</typeparam>
+    /// <param name="this">The object on which this method was called.</param>
+    /// <param name="condition">The condition to check.</param>
+    /// <param name="arg1">The First additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="arg2">The second additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="arg3">The third additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="action">The action to perform on <paramref name="this"/> and the additional arguments.</param>
+    /// <returns>A reference to <paramref name="this"/> after <paramref name="action"/> returns.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// <para><paramref name="this"/> is <see langword="null"/>.</para>
+    /// <para>- or -</para>
+    /// <para><paramref name="action"/> is <see langword="null"/>.</para>
+    /// </exception>
+    public static T InvokeIf<T, TArg1, TArg2, TArg3>(this T @this, bool condition, TArg1 arg1, TArg2 arg2, TArg3 arg3, Action<T, TArg1, TArg2, TArg3> action)
+    {
+        Guard.IsNotNull(@this);
+        Guard.IsNotNull(action);
+
+        if (condition)
+        {
+            action(@this, arg1, arg2, arg3);
+        }
+
+        return @this;
+    }
+
+    /// <summary>
+    /// Invokes an action on an object and additional arguments if a condition if satisfied, then returns the same object.
+    /// </summary>
+    /// <typeparam name="T">The type of the object.</typeparam>
+    /// <typeparam name="TArg1">The type of the first additional parameter to <paramref name="action"/>.</typeparam>
+    /// <typeparam name="TArg2">The type of the second additional parameter to <paramref name="action"/>.</typeparam>
+    /// <typeparam name="TArg3">The type of the third additional parameter to <paramref name="action"/>.</typeparam>
+    /// <typeparam name="TArg4">The type of the fourth additional parameter to <paramref name="action"/>.</typeparam>
+    /// <param name="this">The object on which this method was called.</param>
+    /// <param name="condition">The condition to check.</param>
+    /// <param name="arg1">The First additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="arg2">The second additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="arg3">The third additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="arg4">The fourth additional argument to pass tp <paramref name="action"/>.</param>
+    /// <param name="action">The action to perform on <paramref name="this"/> and the additional arguments.</param>
+    /// <returns>A reference to <paramref name="this"/> after <paramref name="action"/> returns.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// <para><paramref name="this"/> is <see langword="null"/>.</para>
+    /// <para>- or -</para>
+    /// <para><paramref name="action"/> is <see langword="null"/>.</para>
+    /// </exception>
+    public static T InvokeIf<T, TArg1, TArg2, TArg3, TArg4>(this T @this, bool condition, TArg1 arg1, TArg2 arg2, TArg3 arg3, TArg4 arg4, Action<T, TArg1, TArg2, TArg3, TArg4> action)
+    {
+        Guard.IsNotNull(@this);
+        Guard.IsNotNull(action);
+
+        if (condition)
+        {
+            action(@this, arg1, arg2, arg3, arg4);
+        }
+
+        return @this;
+    }
+}

src/Louis/PublicAPI.Unshipped.txt

@@ -86,7 +86,16 @@ static Louis.Fluency.FluentExtensions.IfElse<T>(this T this, bool condition, Lou
 static Louis.Fluency.FluentExtensions.IfElse<T>(this T this, bool condition, System.Action<T>! then, System.Action<T>! else) -> T
 static Louis.Fluency.FluentExtensions.IfNotNull<T, T1>(this T this, T1? arg, Louis.Fluency.FluentAction<T, T1>! then) -> T
 static Louis.Fluency.FluentExtensions.IfNotNull<T, T1>(this T this, T1? arg, System.Action<T, T1>! then) -> T
+static Louis.Fluency.FluentExtensions.Invoke<T, TArg1, TArg2, TArg3, TArg4>(this T this, TArg1 arg1, TArg2 arg2, TArg3 arg3, TArg4 arg4, System.Action<T, TArg1, TArg2, TArg3, TArg4>! action) -> T
+static Louis.Fluency.FluentExtensions.Invoke<T, TArg1, TArg2, TArg3>(this T this, TArg1 arg1, TArg2 arg2, TArg3 arg3, System.Action<T, TArg1, TArg2, TArg3>! action) -> T
+static Louis.Fluency.FluentExtensions.Invoke<T, TArg1, TArg2>(this T this, TArg1 arg1, TArg2 arg2, System.Action<T, TArg1, TArg2>! action) -> T
+static Louis.Fluency.FluentExtensions.Invoke<T, TArg>(this T this, TArg arg, System.Action<T, TArg>! action) -> T
 static Louis.Fluency.FluentExtensions.Invoke<T>(this T this, System.Action<T>! action) -> T
+static Louis.Fluency.FluentExtensions.InvokeIf<T, TArg1, TArg2, TArg3, TArg4>(this T this, bool condition, TArg1 arg1, TArg2 arg2, TArg3 arg3, TArg4 arg4, System.Action<T, TArg1, TArg2, TArg3, TArg4>! action) -> T
+static Louis.Fluency.FluentExtensions.InvokeIf<T, TArg1, TArg2, TArg3>(this T this, bool condition, TArg1 arg1, TArg2 arg2, TArg3 arg3, System.Action<T, TArg1, TArg2, TArg3>! action) -> T
+static Louis.Fluency.FluentExtensions.InvokeIf<T, TArg1, TArg2>(this T this, bool condition, TArg1 arg1, TArg2 arg2, System.Action<T, TArg1, TArg2>! action) -> T
+static Louis.Fluency.FluentExtensions.InvokeIf<T, TArg>(this T this, bool condition, TArg arg, System.Action<T, TArg>! action) -> T
+static Louis.Fluency.FluentExtensions.InvokeIf<T>(this T this, bool condition, System.Action<T>! action) -> T
 static Louis.Fluency.FluentExtensions.Switch<T, TValue>(this T this, TValue value, Louis.Fluency.FluentAction<T>? default, params (TValue Comparand, Louis.Fluency.FluentAction<T>? Action)[]! cases) -> T
 static Louis.Fluency.FluentExtensions.Switch<T, TValue>(this T this, TValue value, Louis.Fluency.FluentAction<T>? default, params (TValue Comparand, System.Action<T>? Action)[]! cases) -> T
 static Louis.Fluency.FluentExtensions.Switch<T, TValue>(this T this, TValue value, params (TValue Comparand, Louis.Fluency.FluentAction<T>? Action)[]! cases) -> T