feature(Result): add mechanism to execute an action based on the state of the previous result

Author: daht-x

libraries/core/documentation/monads/result.md

@@ -36,6 +36,7 @@ Type intended to handle both the possible failure and the expected success of a
    - [`Ensure<TAuxiliary>(createAuxiliary, predicate, createFailure)`](#ensuretauxiliarycreateauxiliary-predicate-createfailure)
    - [`DoOnFailure(execute)`](#doonfailureexecute)
    - [`DoOnSuccess(execute)`](#doonsuccessexecute)
+   - [`Match(doOnFailure, doOnSuccess)`](#matchdoonfailure-doonsuccess)
    - [`Map<TSuccessToMap>(successToMap)`](#maptsuccesstomapsuccesstomap)
    - [`Map<TSuccessToMap>(createSuccessToMap)`](#maptsuccesstomapcreatesuccesstomap)
    - [`Bind<TSuccessToBind>(createResultToBind)`](#bindtsuccesstobindcreateresulttobind)
@@ -429,6 +430,30 @@ Type of expected success.
 
 ***[Top](#resulttfailure-tsuccess)***
 
+#### `Match(doOnFailure, doOnSuccess)`
+
+- Signatures:
+
+  - ```cs
+    public Result<TFailure, TSuccess> Match(Action doOnFailure, Action doOnSuccess)
+    ```
+
+  - ```cs
+    public Result<TFailure, TSuccess> Match(Action<TFailure> doOnFailure, Action<TSuccess> doOnSuccess)
+    ```
+
+- Description: Executes an action based on the state of the previous result.
+- Parameters:
+
+  | Name          | Description                                                |
+  |:--------------|:-----------------------------------------------------------|
+  | `doOnFailure` | The action to execute if the previous result is failed     |
+  | `doOnSuccess` | The action to execute if the previous result is successful |
+
+- Return: The previous result.
+
+***[Top](#resulttfailure-tsuccess)***
+
 #### `Map<TSuccessToMap>(successToMap)`
 
 - Signature:

libraries/core/source/Monads/Result.cs

@@ -224,6 +224,36 @@ public Result<TFailure, TSuccess> DoOnSuccess(Action<TSuccess> execute)
 		return this;
 	}
 
+	/// <summary>Executes an actions based on the state of the previous result.</summary>
+	/// <param name="doOnFailure">The action to execute if the previous result is failed.</param>
+	/// <param name="doOnSuccess">The action to execute if the previous result is successful.</param>
+	/// <returns>The previous result.</returns>
+	public Result<TFailure, TSuccess> Match(Action doOnFailure, Action doOnSuccess)
+	{
+		if (IsFailed)
+		{
+			doOnFailure();
+			return this;
+		}
+		doOnSuccess();
+		return this;
+	}
+
+	/// <summary>Executes an action based on the state of the previous result.</summary>
+	/// <param name="doOnFailure">The action to execute if the previous result is failed.</param>
+	/// <param name="doOnSuccess">The action to execute if the previous result is successful.</param>
+	/// <returns>The previous result.</returns>
+	public Result<TFailure, TSuccess> Match(Action<TFailure> doOnFailure, Action<TSuccess> doOnSuccess)
+	{
+		if (IsFailed)
+		{
+			doOnFailure(Failure);
+			return this;
+		}
+		doOnSuccess(Success);
+		return this;
+	}
+
 	/// <summary>Maps the expected success to a value of another type.</summary>
 	/// <param name="successToMap">An expected success to map.</param>
 	/// <typeparam name="TSuccessToMap">Type of expected success to map.</typeparam>

libraries/core/tests/unit/Monads/ResultTests.cs

@@ -20,6 +20,8 @@ public sealed class ResultTests
 
 	private const string memberDoOnSuccess = nameof(Result<object, object>.DoOnSuccess);
 
+	private const string memberMatch = nameof(Result<object, object>.Match);
+
 	private const string memberMap = nameof(Result<object, object>.Map);
 
 	private const string memberBind = nameof(Result<object, object>.Bind);
@@ -578,6 +580,70 @@ public void DoOnSuccess_SuccessfulResultPlusExecuteWithSuccess_SuccessfulResult(
 
 	#endregion
 
+	#region Match
+
+	#region Overload
+
+	[Fact]
+	[Trait(@base, memberMatch)]
+	public void Match_FailedResultPlusDoOnFailurePlusDoOnSuccess_FailedResult()
+	{
+		bool status = false;
+		Action doOnFailure = () => status = true;
+		Action doOnSuccess = () => status = false;
+		Result<string, Constellation> actual = ResultMother.Fail()
+			.Match(doOnFailure, doOnSuccess);
+		Assert.True(status);
+		ResultAsserter.CheckIfIsFailed(actual);
+	}
+
+	[Fact]
+	[Trait(@base, memberMatch)]
+	public void Match_SuccessfulResultPlusDoOnFailurePlusDoOnSuccess_SuccessfulResult()
+	{
+		bool status = false;
+		Action doOnFailure = () => status = false;
+		Action doOnSuccess = () => status = true;
+		Result<string, Constellation> actual = ResultMother.Succeed()
+			.Match(doOnFailure, doOnSuccess);
+		Assert.True(status);
+		ResultAsserter.CheckIfIsSuccessful(actual);
+	}
+
+	#endregion
+
+	#region Overload
+
+	[Fact]
+	[Trait(@base, memberMatch)]
+	public void Match_FailedResultPlusDoOnFailureWithFailurePlusDoOnSuccessWithSuccess_FailedResult()
+	{
+		bool status = false;
+		Action<string> doOnFailure = _ => status = true;
+		Action<Constellation> doOnSuccess = _ => status = false;
+		Result<string, Constellation> actual = ResultMother.Fail()
+			.Match(doOnFailure, doOnSuccess);
+		Assert.True(status);
+		ResultAsserter.CheckIfIsFailed(actual);
+	}
+
+	[Fact]
+	[Trait(@base, memberMatch)]
+	public void Match_SuccessfulResultPlusDoOnFailureWithFailurePlusDoOnSuccessWithSuccess_SuccessfulResult()
+	{
+		bool status = false;
+		Action<string> doOnFailure = _ => status = false;
+		Action<Constellation> doOnSuccess = _ => status = true;
+		Result<string, Constellation> actual = ResultMother.Succeed()
+			.Match(doOnFailure, doOnSuccess);
+		Assert.True(status);
+		ResultAsserter.CheckIfIsSuccessful(actual);
+	}
+
+	#endregion
+
+	#endregion
+
 	#region Map
 
 	#region Overload