├── LICENSE
├── img
    └── logo.png
├── .gitignore
├── tests
    └── Ultimately.Tests
    │   ├── Properties
    │       └── AssemblyInfo.cs
    │   ├── Ultimately.Tests.csproj
    │   ├── EitherTests.cs
    │   └── CollectionTests.cs
├── src
    ├── Ultimately.csproj
    ├── Reasons
    │   ├── ExceptionalError.cs
    │   ├── Reason.cs
    │   ├── ReasonStringBuilder.cs
    │   ├── Success.cs
    │   └── Error.cs
    ├── Option_Unit_Lazy.cs
    ├── Utilities
    │   ├── MissingReasons.cs
    │   └── TryParse.cs
    ├── Option_Unit.cs
    ├── OptionExtensions.cs
    ├── Optional.cs
    ├── Collections
    │   └── OptionCollectionExtensions.cs
    └── Option_Either.cs
├── Ultimately.sln
└── README.md


/LICENSE:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/silkfire/Ultimately/HEAD/LICENSE


--------------------------------------------------------------------------------
/img/logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/silkfire/Ultimately/HEAD/img/logo.png


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | *.suo
2 | *.user
3 | _ReSharper.*
4 | .vs
5 | bin
6 | obj
7 | packages
8 | 


--------------------------------------------------------------------------------
/tests/Ultimately.Tests/Properties/AssemblyInfo.cs:
--------------------------------------------------------------------------------
 1 | using System.Reflection;
 2 | using System.Runtime.InteropServices;
 3 | 
 4 | [assembly: AssemblyTitle("Optional.Tests")]
 5 | [assembly: AssemblyDescription("")]
 6 | [assembly: AssemblyConfiguration("")]
 7 | [assembly: AssemblyCompany("")]
 8 | [assembly: AssemblyProduct("Ultimately.Tests")]
 9 | [assembly: AssemblyCopyright("Copyright © 2019")]
10 | [assembly: AssemblyTrademark("")]
11 | [assembly: AssemblyCulture("")]
12 | 
13 | [assembly: AssemblyVersion("1.0.0.0")]
14 | [assembly: AssemblyFileVersion("1.0.0.0")]
15 | 
16 | [assembly: ComVisible(false)]
17 | 


--------------------------------------------------------------------------------
/src/Ultimately.csproj:
--------------------------------------------------------------------------------
 1 | <Project Sdk="Microsoft.NET.Sdk">
 2 | 
 3 |   <PropertyGroup>
 4 |     <TargetFramework>net10.0</TargetFramework>
 5 |     <Authors>Gabriel Bider, Nils Lück, Michael Altmann</Authors>
 6 |     <PackageTags>option optional some none maybe either null monad monadic result results resultful fluentresults functional pipeline pipelines</PackageTags>
 7 |     <PackageProjectUrl>https://github.com/silkfire/Ultimately</PackageProjectUrl>
 8 |     <Description>A robust option type for C#.</Description>
 9 |     <Version>4.0.0</Version>
10 |     <AssemblyVersion>4.0.0.0</AssemblyVersion>
11 |     <PackageReleaseNotes>4.0.0 Target .NET 10</PackageReleaseNotes>
12 |   </PropertyGroup>
13 | 
14 | </Project>


--------------------------------------------------------------------------------
/tests/Ultimately.Tests/Ultimately.Tests.csproj:
--------------------------------------------------------------------------------
 1 | <Project Sdk="Microsoft.NET.Sdk">
 2 | 
 3 |   <PropertyGroup>
 4 |     <TargetFramework>net10.0</TargetFramework>
 5 |     <TargetLatestRuntimePatch>true</TargetLatestRuntimePatch>
 6 | 
 7 |     <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
 8 |     <Authors>Gabriel Bider, Nils Lück</Authors>
 9 |     <NoWarn>1591</NoWarn>
10 |   </PropertyGroup>
11 | 
12 |   <ItemGroup>
13 |     <PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.0.1" />
14 |     <PackageReference Include="xunit.runner.visualstudio" Version="3.1.5">
15 |       <PrivateAssets>all</PrivateAssets>
16 |       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
17 |     </PackageReference>
18 |     <PackageReference Include="xunit.v3" Version="3.2.0" />
19 |   </ItemGroup>
20 | 
21 |   <ItemGroup>
22 |     <ProjectReference Include="..\..\src\Ultimately.csproj" />
23 |   </ItemGroup>
24 | 
25 | </Project>


--------------------------------------------------------------------------------
/src/Reasons/ExceptionalError.cs:
--------------------------------------------------------------------------------
 1 | namespace Ultimately.Reasons;
 2 | 
 3 | using System;
 4 | 
 5 | /// <summary>
 6 | /// Represents an error that is associated with a specific exception instance.
 7 | /// </summary>
 8 | public sealed class ExceptionalError : Error
 9 | {
10 |     /// <summary>
11 |     /// Gets the exception associated with this error.
12 |     /// </summary>
13 |     public Exception Exception { get; }
14 | 
15 |     private ExceptionalError(string message, Exception exception) : base(message)
16 |     {
17 |         Exception = exception;
18 |     }
19 | 
20 |     /// <summary>
21 |     /// Creates a new <see cref="ExceptionalError"/> instance that wraps the specified exception.
22 |     /// </summary>
23 |     /// <param name="exception">The exception to wrap.</param>
24 |     public static ExceptionalError Create(Exception exception)
25 |     {
26 |         return new ExceptionalError(exception.Message, exception);
27 |     }
28 | 
29 |     /// <inheritdoc/>
30 |     protected internal override ReasonStringBuilder GetReasonStringBuilder()
31 |     {
32 |         return new ReasonStringBuilder().WithInfoNoQuotes("", $"{Exception.GetType().Name}: '{Message}'");
33 |     }
34 | }
35 | 


--------------------------------------------------------------------------------
/src/Reasons/Reason.cs:
--------------------------------------------------------------------------------
 1 | namespace Ultimately.Reasons;
 2 | 
 3 | using System.Collections.Generic;
 4 | 
 5 | // https://github.com/altmann/FluentResults
 6 | /// <summary>
 7 | /// Base class for representing reasons for success or failure.
 8 | /// </summary>
 9 | public abstract class Reason
10 | {
11 |     /// <summary>
12 |     /// Gets the message associated with the current object.
13 |     /// </summary>
14 |     public string Message { get; protected set; }
15 | 
16 |     /// <summary>
17 |     /// Gets the collection of key-value pairs that store additional metadata associated with the object.
18 |     /// </summary>
19 |     public Dictionary<string, object> Metadata { get; protected set; } = [];
20 | 
21 |     /// <summary>
22 |     /// Gets a <see cref="ReasonStringBuilder"/> for this reason.
23 |     /// </summary>
24 |     protected internal virtual ReasonStringBuilder GetReasonStringBuilder()
25 |     {
26 |         return new ReasonStringBuilder().WithReasonType(GetType())
27 |                                         .WithInfo("", Message)
28 |                                         .WithInfo(nameof(Metadata), string.Join("; ", Metadata));
29 |     }
30 | 
31 |     /// <summary>
32 |     /// Returns a string representation of the reason.
33 |     /// </summary>
34 |     public override string ToString()
35 |     {
36 |         return GetReasonStringBuilder().Build();
37 |     }
38 | }
39 | 


--------------------------------------------------------------------------------
/Ultimately.sln:
--------------------------------------------------------------------------------
 1 | 
 2 | Microsoft Visual Studio Solution File, Format Version 12.00
 3 | # Visual Studio Version 16
 4 | VisualStudioVersion = 16.0.28803.352
 5 | MinimumVisualStudioVersion = 10.0.40219.1
 6 | Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Ultimately", "src\Ultimately.csproj", "{BDAE4370-B7A7-41B4-BCF9-8D201C811914}"
 7 | EndProject
 8 | Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Ultimately.Tests", "tests\Ultimately.Tests\Ultimately.Tests.csproj", "{12606143-9C9B-4A92-81D5-CEA814AC64AC}"
 9 | EndProject
10 | Global
11 | 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
12 | 		Debug|Any CPU = Debug|Any CPU
13 | 		Release|Any CPU = Release|Any CPU
14 | 	EndGlobalSection
15 | 	GlobalSection(ProjectConfigurationPlatforms) = postSolution
16 | 		{BDAE4370-B7A7-41B4-BCF9-8D201C811914}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
17 | 		{BDAE4370-B7A7-41B4-BCF9-8D201C811914}.Debug|Any CPU.Build.0 = Debug|Any CPU
18 | 		{BDAE4370-B7A7-41B4-BCF9-8D201C811914}.Release|Any CPU.ActiveCfg = Release|Any CPU
19 | 		{BDAE4370-B7A7-41B4-BCF9-8D201C811914}.Release|Any CPU.Build.0 = Release|Any CPU
20 | 		{12606143-9C9B-4A92-81D5-CEA814AC64AC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
21 | 		{12606143-9C9B-4A92-81D5-CEA814AC64AC}.Debug|Any CPU.Build.0 = Debug|Any CPU
22 | 		{12606143-9C9B-4A92-81D5-CEA814AC64AC}.Release|Any CPU.ActiveCfg = Release|Any CPU
23 | 		{12606143-9C9B-4A92-81D5-CEA814AC64AC}.Release|Any CPU.Build.0 = Release|Any CPU
24 | 	EndGlobalSection
25 | 	GlobalSection(SolutionProperties) = preSolution
26 | 		HideSolutionNode = FALSE
27 | 	EndGlobalSection
28 | 	GlobalSection(ExtensibilityGlobals) = postSolution
29 | 		SolutionGuid = {E57277B7-1604-4E19-94FB-95F188F94526}
30 | 	EndGlobalSection
31 | EndGlobal
32 | 


--------------------------------------------------------------------------------
/src/Option_Unit_Lazy.cs:
--------------------------------------------------------------------------------
 1 | namespace Ultimately;
 2 | 
 3 | using Reasons;
 4 | 
 5 | using System;
 6 | using System.Threading.Tasks;
 7 | 
 8 | /// <summary>
 9 | /// Wraps a predicate that returns a successful or an unsuccessful outcome.
10 | /// </summary>
11 | public readonly struct LazyOption
12 | {
13 |     internal Func<bool> OutcomeDelegate { get; }
14 | 
15 |     internal Success Success { get; }
16 | 
17 |     internal Error Error { get; }
18 | 
19 |     internal LazyOption(Func<bool> outcomeDelegate, Success success, Error error)
20 |     {
21 |         OutcomeDelegate = outcomeDelegate;
22 |         Success = success;
23 |         Error = error;
24 |     }
25 | 
26 |     /// <summary>
27 |     /// Resolves the outcome delegate of the optional, returning a regular optional whose outcome depends on the result of the delegate.
28 |     /// </summary>
29 |     /// <returns></returns>
30 |     public Option Resolve()
31 |     {
32 |         return OutcomeDelegate() ? Optional.Some(Success) : Optional.None(Error);
33 |     }
34 | }
35 | 
36 | /// <summary>
37 | /// Wraps a predicate task that returns a successful or an unsuccessful outcome.
38 | /// </summary>
39 | public readonly struct LazyOptionAsync
40 | {
41 |     internal Func<Task<bool>> OutcomeDelegate { get; }
42 | 
43 |     internal Success Success { get; }
44 | 
45 |     internal Error Error { get; }
46 | 
47 |     internal LazyOptionAsync(Func<Task<bool>> outcomeDelegate, Success success, Error error)
48 |     {
49 |         OutcomeDelegate = outcomeDelegate;
50 |         Success = success;
51 |         Error = error;
52 |     }
53 | 
54 |     /// <summary>
55 |     /// Resolves the outcome delegate of the optional, returning a regular optional whose outcome depends on the result of the delegate.
56 |     /// </summary>
57 |     /// <returns></returns>
58 |     public async Task<Option> Resolve()
59 |     {
60 |         return await OutcomeDelegate() ? Optional.Some(Success) : Optional.None(Error);
61 |     }
62 | }
63 | 


--------------------------------------------------------------------------------
/src/Reasons/ReasonStringBuilder.cs:
--------------------------------------------------------------------------------
 1 | namespace Ultimately.Reasons;
 2 | 
 3 | using System;
 4 | using System.Collections.Generic;
 5 | 
 6 | /// <summary>
 7 | /// Helper class for building reason strings.
 8 | /// </summary>
 9 | public sealed class ReasonStringBuilder
10 | {
11 |     private  string _reasonType = string.Empty;
12 |     private readonly List<string> _infoStrings = [];
13 | 
14 |     /// <summary>
15 |     /// Sets the reason type based on the provided type's name.
16 |     /// </summary>
17 |     /// <param name="type">The type to set as the reason type.</param>
18 |     public ReasonStringBuilder WithReasonType(Type type)
19 |     {
20 |         _reasonType = type.Name;
21 | 
22 |         return this;
23 |     }
24 | 
25 |     /// <summary>
26 |     /// Adds an informational label-value pair to the reason string.
27 |     /// </summary>
28 |     /// <param name="label">The label for the information.</param>
29 |     /// <param name="value">The value for the information.</param>
30 |     public ReasonStringBuilder WithInfo(string label, string value)
31 |     {
32 |         var infoString = ToLabelValueStringOrEmpty(label, value);
33 | 
34 |         if (!string.IsNullOrEmpty(infoString))
35 |         {
36 |             _infoStrings.Add(infoString);
37 |         }
38 | 
39 |         return this;
40 |     }
41 | 
42 |     /// <summary>
43 |     /// Appends an informational label and value pair to the builder without surrounding the value in quotes.
44 |     /// </summary>
45 |     /// <param name="label">The label to associate with the value. Cannot be null.</param>
46 |     /// <param name="value">The value to append. If null or empty, the pair is not added.</param>
47 |     public ReasonStringBuilder WithInfoNoQuotes(string label, string value)
48 |     {
49 |         var infoString = ToLabelValueStringOrEmptyNoQuotes(label, value);
50 | 
51 |         if (!string.IsNullOrEmpty(infoString))
52 |         {
53 |             _infoStrings.Add(infoString);
54 |         }
55 | 
56 |         return this;
57 |     }
58 | 
59 |     /// <summary>
60 |     /// Builds and returns a string representation of the current reason type and its associated information.
61 |     /// </summary>
62 |     /// <returns>A string that combines the reason type and its related information. If no information is present, only the
63 |     /// reason type is returned.</returns>
64 |     internal string Build()
65 |     {
66 |         var reasonInfoText = _infoStrings.Count != 0
67 |             ? ReasonInfosToString(_infoStrings)
68 |             : string.Empty;
69 | 
70 |         return $"{_reasonType}{(_reasonType != "" ? "=" : "")}{reasonInfoText}";
71 |     }
72 | 
73 |     private static string ReasonInfosToString(IEnumerable<string> infoStrings)
74 |     {
75 |         return string.Join(", ", infoStrings);
76 |     }
77 | 
78 |     private static string ToLabelValueStringOrEmpty(string label, string value)
79 |     {
80 |         if (string.IsNullOrEmpty(value))
81 |         {
82 |             return string.Empty;
83 |         }
84 | 
85 |         return $"{(label != "" ? $"{label}=" : "")}'{value}'";
86 |     }
87 | 
88 |     private static string ToLabelValueStringOrEmptyNoQuotes(string label, string value)
89 |     {
90 |         if (string.IsNullOrEmpty(value))
91 |         {
92 |             return string.Empty;
93 |         }
94 | 
95 |         return $"{(label != "" ? $"{label}=" : "")}{value}";
96 |     }
97 | }
98 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | Ultimately: [Optional](https://github.com/nlkl/Optional) + [FluentResults](https://github.com/altmann/FluentResults) = ❤
 2 | -
 3 | 
 4 | ![logo](https://github.com/silkfire/Ultimately/blob/master/img/logo.png)
 5 | 
 6 | [![NuGet](https://img.shields.io/nuget/v/Ultimately.svg)](https://www.nuget.org/packages/Ultimately)
 7 | 
 8 | **Ultimately** provides a robust either type with rich error and success models for C#.
 9 | 
10 | ## What and Why?
11 | 
12 | An `Option` is a strongly typed alternative to null values that lets you:
13 | 
14 | * Avoid those pesky null-reference exceptions
15 | * Signal intent and model your data more explictly
16 | * Cut down on manual null checks and focus on your domain
17 | 
18 | ## Core concepts
19 | 
20 | The core concept behind Ultimately is derived from two common functional programming constructs – referred to as the *Unit* type and the *Either* type (referred to as `Option` and `Option<TValue>` in Ultimately).
21 | 
22 | Many functional programming languages disallow null values, as null references can introduce hard-to-find bugs. The Either and the Unit types are both a type-safe alternative to null values.
23 | 
24 | In general, an `Option`/`Option<TValue>` can be in one of two states: **Some** (representing a *successful* outcome in the case of a Unit optional and the *presence* of a value in the case of an Either optional) and **None** (representing an *unsuccessful* outcome – or the *lack* of a value – respectively). Unlike null, an option type forces the user to check if a value is actually present, thereby mitigating many of the problems of null values.
25 | 
26 | `Option` and `Option<TValue>` are structs in Ultimately, making it impossible to assign a null value to either of them.
27 | 
28 | Furthermore, an option type is a lot more explicit than a null value, which can make APIs based on optional values a lot easier to understand. Now, the type signature will indicate if a value can be missing!
29 | 
30 | The Unit type (`Option`) is a specialized Either type, conceptually the equivalent of `Option<bool>`. The only difference is that instead of containing a true/false value, you can verify the outcome by simply checking the `IsSuccessful` flag.
31 | 
32 | Finally, Ultimately offers several utility methods that makes it easy and convenient to work with both of the above described optional types.
33 | 
34 | ## Rich reason models
35 | 
36 | Ultimately has borrowed heavily on the concept of rich reason models found in FluentResults. Its premise is that an object with information is attached to the optional, describing the reason on why it arrived to its current state. This object is named `Success` in the case of an optional with a successful outcome / presence of a value and `Error` in the case of the opposite. It also allows you to store arbitrary metadata in the form of a dictionary, allowing of very detailed information about the optional's state.
37 | 
38 | ### Error model
39 | 
40 | The Error model is, for obvious reasons, the most used of the two reason models. Almost all methods in Ultimately require an Error object to be provided with an error message describing the outcome of a failed scenario pertaining to the method called.
41 | 
42 | An instance of the class can either be created with
43 | 
44 | Error.Create("Reason why a premise/predicate/validation fails")
45 | 
46 | or just by providing the message as a string argument, as the class has an implicit conversion from `string` to `Error`.
47 | 
48 | The beauty of the Error model is that it allows you to chain multiple errors, visualizing an error event chain, similar to exceptions with inner exceptions. This is done by calling the `CausedBy()` method and supplying another error object.
49 | 
50 | The Visual Studio debugger will display this relationship in a very easy to follow way.
51 | 
52 | 
53 | 
54 | *to be continued*
55 | 


--------------------------------------------------------------------------------
/src/Utilities/MissingReasons.cs:
--------------------------------------------------------------------------------
 1 | namespace Ultimately.Utilities;
 2 | 
 3 | using System;
 4 | using System.Collections.Generic;
 5 | using System.Linq;
 6 | 
 7 | internal static class MissingReasons
 8 | {
 9 |     // https://stackoverflow.com/a/1362899/633098
10 | 
11 |     private static readonly Dictionary<Type, string> _typeAliases = new()
12 |                                                                     {
13 |                                                                         [typeof(byte)]    = "byte",
14 |                                                                         [typeof(sbyte)]   = "sbyte",
15 |                                                                         [typeof(short)]   = "short",
16 |                                                                         [typeof(ushort)]  = "ushort",
17 |                                                                         [typeof(int)]     = "int",
18 |                                                                         [typeof(uint)]    = "uint",
19 |                                                                         [typeof(long)]    = "long",
20 |                                                                         [typeof(ulong)]   = "ulong",
21 |                                                                         [typeof(float)]   = "float",
22 |                                                                         [typeof(double)]  = "double",
23 |                                                                         [typeof(decimal)] = "decimal",
24 |                                                                         [typeof(object)]  = "object",
25 |                                                                         [typeof(bool)]    = "bool",
26 |                                                                         [typeof(char)]    = "char",
27 |                                                                         [typeof(string)]  = "string",
28 |                                                                         [typeof(void)]    = "void"
29 |                                                                     };
30 | 
31 | 
32 |     public const string KeyNotFound = "A key was not found in a dictionary.";
33 | 
34 |     public const string KeyNotFoundIndexer = "A key was not found in a type implementing an indexer.";
35 | 
36 |     public const string IndexNotFound = "An element was not found at a given index in a collection.";
37 | 
38 |     public const string CollectionWasEmpty = "A sequence or collection contained no elements.";
39 | 
40 |     public const string NoElementsFound = "No element matching the given predicate was found.";
41 | 
42 |     public static class CouldNotBeParsedAs<T>
43 |     {
44 |         public static string Value { get; } = $"A string could not be parsed as a value of type ´{typeof(T).PrettyName()}´";
45 |     }
46 | 
47 | 
48 |     /// <summary>
49 |     /// Returns a pretty name for the type, such as using angle braces for a generic type.
50 |     /// </summary>
51 |     /// <param name="type">The type.</param>
52 |     private static string PrettyName(this Type type)
53 |     {
54 |         if (_typeAliases.TryGetValue(type, out var prettyName))
55 |         {
56 |             return prettyName;
57 |         }
58 | 
59 |         if (type.GetGenericArguments().Length == 0)
60 |         {
61 |             return type.Name;
62 |         }
63 | 
64 |         var genericArguments = type.GetGenericArguments();
65 |         var unmangledName = type.JustTypeName();
66 | 
67 |         return $"{unmangledName}<{string.Join(",", genericArguments.Select(PrettyName).ToArray())}>";
68 |     }
69 | 
70 |     /// <summary>
71 |     /// Returns the name of the type, without the ` symbol or generic type parameterization.
72 |     /// </summary>
73 |     /// <param name="type">The type.</param>
74 |     private static string JustTypeName(this Type type)
75 |     {
76 |         var typeDefinition = type.Name;
77 |         var indexOf = typeDefinition.IndexOf('`');
78 | 
79 |         return indexOf < 0 ? typeDefinition : typeDefinition[..indexOf];
80 |     }
81 | }
82 | 


--------------------------------------------------------------------------------
/src/Reasons/Success.cs:
--------------------------------------------------------------------------------
  1 | namespace Ultimately.Reasons;
  2 | 
  3 | using System;
  4 | using System.Collections.Generic;
  5 | using System.Linq;
  6 | 
  7 | /// <summary>
  8 | /// Represents a successful outcome with associated reasons.
  9 | /// </summary>
 10 | public class Success : Reason
 11 | {
 12 |     /// <summary>
 13 |     /// Gets a default success instance with an empty message.
 14 |     /// </summary>
 15 |     public static Success Default => new("");
 16 | 
 17 |     /// <summary>
 18 |     /// Gets the list of reasons that led to this success.
 19 |     /// </summary>
 20 |     public List<Success> Reasons { get; }
 21 | 
 22 |     private Success()
 23 |     {
 24 |         Reasons = [];
 25 |     }
 26 | 
 27 |     private Success(string message) : this()
 28 |     {
 29 |         Message = message;
 30 |     }
 31 | 
 32 |     private Success(string message, Success enabledBy) : this(message)
 33 |     {
 34 |         Reasons.Add(enabledBy);
 35 |     }
 36 | 
 37 |     /// <summary>
 38 |     /// Creates a new <see cref="Success"/> instance with the specified message.
 39 |     /// </summary>
 40 |     /// <param name="message">The success message.</param>
 41 |     public static Success Create(string message)
 42 |     {
 43 |         return new Success(message);
 44 |     }
 45 | 
 46 |     /// <summary>
 47 |     /// Creates a new <see cref="Success"/> instance with the specified message and the <see cref="Success"/> instance that this instance is enabled by.
 48 |     /// </summary>
 49 |     /// <param name="message">The message that describes the success.</param>
 50 |     /// <param name="enabledBy">A <see cref="Success"/> instance that this success is based on.</param>
 51 |     public static Success Create(string message, Success enabledBy)
 52 |     {
 53 |         return new Success(message, enabledBy);
 54 |     }
 55 | 
 56 |     /// <summary>
 57 |     /// Adds the success reason that enabled this success.
 58 |     /// </summary>
 59 |     /// <param name="message">The message of the success that enabled this success.</param>
 60 |     public Success EnabledBy(string message)
 61 |     {
 62 |         Reasons.Add(new Success(message));
 63 | 
 64 |         return this;
 65 |     }
 66 | 
 67 |     /// <summary>
 68 |     /// Adds the <see cref="Success"/> instance that enabled this success.
 69 |     /// </summary>
 70 |     /// <param name="success">The <see cref="Success"/> instance that enabled this success.</param>
 71 |     public Success EnabledBy(Success success)
 72 |     {
 73 |         Reasons.Add(success);
 74 | 
 75 |         return this;
 76 |     }
 77 | 
 78 |     /// <summary>
 79 |     /// Adds the success reason from the specified optional value to the current object if the value is present.
 80 |     /// </summary>
 81 |     /// <typeparam name="TValue">The type of the value contained in the optional parameter.</typeparam>
 82 |     /// <param name="some">An optional value whose associated success reason will be added if present. Must have a value.</param>
 83 |     /// <returns>The current <see cref="Success"/> instance with the success reason added if the optional value is present.</returns>
 84 |     /// <exception cref="InvalidOperationException">Thrown if <paramref name="some"/> does not have a value.</exception>
 85 |     public Success EnabledBy<TValue>(Option<TValue> some)
 86 |     {
 87 |         if (!some.HasValue)
 88 |         {
 89 |             throw new InvalidOperationException("The optional value cannot empty in order to access its success object");
 90 |         }
 91 | 
 92 |         some.MatchSome((_, s) => Reasons.Add(s));
 93 | 
 94 |         return this;
 95 |     }
 96 | 
 97 |     /// <summary>
 98 |     /// Adds the value from a successful optional result to the current success reasons and returns this instance.
 99 |     /// </summary>
100 |     /// <param name="some">The optional value to evaluate. Must represent a successful result.</param>
101 |     /// <returns>This <see cref="Success"/> instance, with the value from <paramref name="some"/> added to its reasons if
102 |     /// successful.</returns>
103 |     /// <exception cref="InvalidOperationException">Thrown if <paramref name="some"/> does not represent a successful result.</exception>
104 |     public Success EnabledBy(Option some)
105 |     {
106 |         if (!some.IsSuccessful)
107 |         {
108 |             throw new InvalidOperationException("The optional value cannot unsuccessful in order to access its success object");
109 |         }
110 | 
111 |         some.MatchSome(s => Reasons.Add(s));
112 | 
113 |         return this;
114 |     }
115 | 
116 |     /// <summary>
117 |     /// Adds the specified metadata to the <see cref="Success"/> instance and returns the updated instance.
118 |     /// </summary>
119 |     /// <param name="name">The name of the metadata.</param>
120 |     /// <param name="value">The value of the metadata.</param>
121 |     public Success WithMetadata(string name, object value)
122 |     {
123 |         Metadata.Add(name, value);
124 | 
125 |         return this;
126 |     }
127 | 
128 |     /// <summary>
129 |     /// Adds the specified metadata entries to this <see cref="Success"/> instance and returns the updated instance.
130 |     /// </summary>
131 |     /// <param name="metadata">A dictionary containing metadata key-value pairs to add.</param>
132 |     public Success WithMetadata(Dictionary<string, object> metadata)
133 |     {
134 |         foreach (var metadataItem in metadata)
135 |         {
136 |             Metadata.Add(metadataItem.Key, metadataItem.Value);
137 |         }
138 | 
139 |         return this;
140 |     }
141 | 
142 |     /// <inheritdoc/>
143 |     protected internal override ReasonStringBuilder GetReasonStringBuilder()
144 |     {
145 |         return new ReasonStringBuilder()
146 |                .WithInfo("", Message)
147 |                .WithInfoNoQuotes(nameof(Metadata), string.Join("; ", Metadata.Select(kvp => $"'{kvp.Key}: {kvp.Value}'")))
148 |                .WithInfoNoQuotes("Anteceded by", $"{string.Join(" ⁎ ", Reasons)}");
149 |     }
150 | }
151 | 


--------------------------------------------------------------------------------
/src/Option_Unit.cs:
--------------------------------------------------------------------------------
  1 | namespace Ultimately;
  2 | 
  3 | using Reasons;
  4 | 
  5 | using System;
  6 | using System.Collections.Generic;
  7 | 
  8 | /// <summary>
  9 | /// An optional that represents either a successful or an unsuccessful outcome.
 10 | /// </summary>
 11 | public readonly struct Option
 12 | {
 13 |     /// <summary>
 14 |     /// Checks whether the optional's outcome is successful.
 15 |     /// </summary>
 16 |     public bool IsSuccessful { get; }
 17 | 
 18 |     internal Success Success { get; }
 19 | 
 20 |     internal Error Error { get; }
 21 | 
 22 |     internal Option(bool isSuccessful, Success success, Error error)
 23 |     {
 24 |         IsSuccessful = isSuccessful;
 25 |         Success = success;
 26 |         Error = error;
 27 |     }
 28 | 
 29 |     /// <summary>
 30 |     /// Returns an enumerator for the optional.
 31 |     /// </summary>
 32 |     /// <returns>The enumerator.</returns>
 33 |     public IEnumerator<Success> GetEnumerator()
 34 |     {
 35 |         if (IsSuccessful)
 36 |         {
 37 |             yield return Success;
 38 |         }
 39 |     }
 40 | 
 41 |     /// <summary>
 42 |     /// Returns an alternative optional if this optional's outcome is unsuccessful.
 43 |     /// </summary>
 44 |     /// <param name="alternativeOption">The alternative optional.</param>
 45 |     /// <returns>The alternative optional, if no value is present, otherwise itself.</returns>
 46 |     public Option Else(Option alternativeOption) => IsSuccessful ? this : alternativeOption;
 47 | 
 48 |     /// <summary>
 49 |     /// Creates an alternative optional if this optional's outcome is unsuccessful.
 50 |     /// </summary>
 51 |     /// <param name="alternativeOptionFactory">A factory function to create an alternative optional.</param>
 52 |     /// <returns>The alternative optional, if no value is present, otherwise itself.</returns>
 53 |     public Option Else(Func<Option> alternativeOptionFactory)
 54 |     {
 55 |         ArgumentNullException.ThrowIfNull(alternativeOptionFactory);
 56 | 
 57 |         return IsSuccessful ? this : alternativeOptionFactory();
 58 |     }
 59 | 
 60 |     /// <summary>
 61 |     /// Evaluates a specified function, based on whether the optional's outcome is successful or not.
 62 |     /// </summary>
 63 |     /// <param name="some">The function to evaluate if the outcome is successful.</param>
 64 |     /// <param name="none">The function to evaluate if the outcome is unsuccessful.</param>
 65 |     /// <returns>The result of the evaluated function.</returns>
 66 |     public TResult Match<TResult>(Func<TResult> some, Func<Error, TResult> none)
 67 |     {
 68 |         ArgumentNullException.ThrowIfNull(some);
 69 | 
 70 |         ArgumentNullException.ThrowIfNull(none);
 71 | 
 72 |         return IsSuccessful ? some() : none(Error);
 73 |     }
 74 | 
 75 |     /// <summary>
 76 |     /// Evaluates a specified function, based on whether the optional's outcome is successful or not.
 77 |     /// </summary>
 78 |     /// <param name="some">The function to evaluate if the outcome is successful.</param>
 79 |     /// <param name="none">The function to evaluate if the outcome is unsuccessful.</param>
 80 |     /// <returns>The result of the evaluated function.</returns>
 81 |     public TResult Match<TResult>(Func<Success, TResult> some, Func<Error, TResult> none)
 82 |     {
 83 |         ArgumentNullException.ThrowIfNull(some);
 84 | 
 85 |         ArgumentNullException.ThrowIfNull(none);
 86 | 
 87 |         return IsSuccessful ? some(Success) : none(Error);
 88 |     }
 89 | 
 90 |     /// <summary>
 91 |     /// Evaluates a specified action, based on whether the optional's outcome is successful or not.
 92 |     /// </summary>
 93 |     /// <param name="some">The function to evaluate if the optional's outcome is succesful.</param>
 94 |     /// <param name="none">The function to evaluate if the optional's outcome is unsuccesful.</param>
 95 |     public void Match(Action some, Action<Error> none)
 96 |     {
 97 |         ArgumentNullException.ThrowIfNull(some);
 98 | 
 99 |         ArgumentNullException.ThrowIfNull(none);
100 | 
101 |         if (IsSuccessful)
102 |         {
103 |             some();
104 |         }
105 |         else
106 |         {
107 |             none(Error);
108 |         }
109 |     }
110 | 
111 |     /// <summary>
112 |     /// Evaluates a specified action, based on whether the optional's outcome is successful or not.
113 |     /// </summary>
114 |     /// <param name="some">The function to evaluate if the optional's outcome is succesful.</param>
115 |     /// <param name="none">The function to evaluate if the optional's outcome is unsuccesful.</param>
116 |     public void Match(Action<Success> some, Action<Error> none)
117 |     {
118 |         ArgumentNullException.ThrowIfNull(some);
119 | 
120 |         ArgumentNullException.ThrowIfNull(none);
121 | 
122 |         if (IsSuccessful)
123 |         {
124 |             some(Success);
125 |         }
126 |         else
127 |         {
128 |             none(Error);
129 |         }
130 |     }
131 | 
132 |     /// <summary>
133 |     /// Evaluates a specified action if the optional's outcome is succesful.
134 |     /// </summary>
135 |     /// <param name="some">The action to evaluate if the optional's outcome is succesful.</param>
136 |     public void MatchSome(Action some)
137 |     {
138 |         ArgumentNullException.ThrowIfNull(some);
139 | 
140 |         if (IsSuccessful)
141 |         {
142 |             some();
143 |         }
144 |     }
145 | 
146 |     /// <summary>
147 |     /// Evaluates a specified action if the optional's outcome is succesful.
148 |     /// </summary>
149 |     /// <param name="some">The action to evaluate if the optional's outcome is succesful.</param>
150 |     public void MatchSome(Action<Success> some)
151 |     {
152 |         ArgumentNullException.ThrowIfNull(some);
153 | 
154 |         if (IsSuccessful)
155 |         {
156 |             some(Success);
157 |         }
158 |     }
159 | 
160 |     /// <summary>
161 |     /// Evaluates a specified action if outcome is unsuccesful.
162 |     /// </summary>
163 |     /// <param name="none">The action to evaluate if outcome is unsuccesful.</param>
164 |     public void MatchNone(Action<Error> none)
165 |     {
166 |         ArgumentNullException.ThrowIfNull(none);
167 | 
168 |         if (!IsSuccessful)
169 |         {
170 |             none(Error);
171 |         }
172 |     }
173 | 
174 |     /// <summary>
175 |     /// Transforms the optional into another optional. The result is flattened, and if either optional's outcome is unsuccessful, an unsuccessful optional is returned.
176 |     /// </summary>
177 |     /// <param name="mapping">The transformation function.</param>
178 |     /// <param name="subsequentError">If the resulting optional's outcome is unsuccessful, sets its error as the direct reason to the specified subsequent error.</param>
179 |     /// <returns>The transformed optional.</returns>
180 |     public Option FlatMap(Func<Option> mapping, Error subsequentError = null)
181 |     {
182 |         ArgumentNullException.ThrowIfNull(mapping);
183 | 
184 |         Option result;
185 | 
186 |         if (IsSuccessful)
187 |         {
188 |             result = mapping();
189 | 
190 |             if (!result.IsSuccessful)
191 |             {
192 |                 if (subsequentError != null)
193 |                 {
194 |                     result = Optional.None(subsequentError.CausedBy(result));
195 |                 }
196 |             }
197 |         }
198 |         else
199 |         {
200 |             result = Optional.None(subsequentError != null ? subsequentError.CausedBy(this) : Error);
201 |         }
202 | 
203 |         return result;
204 |     }
205 | 
206 |     /// <summary>
207 |     /// Transforms the optional into another optional. The result is flattened, and if either optional's outcome is unsuccessful, an unsuccessful optional is returned.
208 |     /// </summary>
209 |     /// <param name="mapping">The transformation function.</param>
210 |     /// <param name="subsequentError">If the resulting optional's outcome is unsuccessful, sets its error as the direct reason to the specified subsequent error.</param>
211 |     /// <returns>The transformed optional.</returns>
212 |     public Option FlatMap(Func<Success, Option> mapping, Error subsequentError = null)
213 |     {
214 |         ArgumentNullException.ThrowIfNull(mapping);
215 | 
216 |         Option result;
217 | 
218 |         if (IsSuccessful)
219 |         {
220 |             result = mapping(Success);
221 | 
222 |             if (!result.IsSuccessful)
223 |             {
224 |                 if (subsequentError != null)
225 |                 {
226 |                     result = Optional.None(subsequentError.CausedBy(result));
227 |                 }
228 |             }
229 |         }
230 |         else
231 |         {
232 |             result = Optional.None(subsequentError != null ? subsequentError.CausedBy(this) : Error);
233 |         }
234 | 
235 |         return result;
236 |     }
237 | 
238 |     /// <summary>
239 |     /// If the current optional's outcome is successful, sets its success reason as the direct reason to the specified subsequent success reason.
240 |     /// </summary>
241 |     /// <param name="success">The successful optional's success reason will be set as the cause of the specified success reason.</param>
242 |     public Option FlatMapSome(Success success)
243 |     {
244 |         ArgumentNullException.ThrowIfNull(success);
245 | 
246 |         if (!IsSuccessful)
247 |         {
248 |             return Optional.Some(success.EnabledBy(this));
249 |         }
250 | 
251 |         return this;
252 |     }
253 | 
254 |     /// <summary>
255 |     /// If the current optional's outcome is unsuccessful, sets its error as the direct reason to the specified subsequent error.
256 |     /// </summary>
257 |     /// <param name="subsequentError">The error of the unsuccessful optional will be set as the cause of the specified error.</param>
258 |     public Option FlatMapNone(Error subsequentError)
259 |     {
260 |         ArgumentNullException.ThrowIfNull(subsequentError);
261 | 
262 |         if (!IsSuccessful)
263 |         {
264 |             return Optional.None(subsequentError.CausedBy(this));
265 |         }
266 | 
267 |         return this;
268 |     }
269 | 
270 |     /// <summary>
271 |     /// Returns a string that represents the current optional.
272 |     /// </summary>
273 |     /// <returns>A string that represents the current optional.</returns>
274 |     public override string ToString()
275 |     {
276 |         if (IsSuccessful)
277 |         {
278 |             return $"Some({(Success.Message != "" || Success.Metadata.Count > 0 ? Success.ToString() : "")})";
279 |         }
280 | 
281 |         return $"None{(Error != null ? $"(Error={Error})" : "")}";
282 |     }
283 | }
284 | 


--------------------------------------------------------------------------------
/src/Reasons/Error.cs:
--------------------------------------------------------------------------------
  1 | namespace Ultimately.Reasons;
  2 | 
  3 | using System;
  4 | using System.Collections.Generic;
  5 | using System.Linq;
  6 | using System.Runtime.CompilerServices;
  7 | 
  8 | /// <summary>
  9 | /// Represents an error with an associated message, optional metadata, and a chain of underlying causes. Provides
 10 | /// methods for constructing error objects, attaching additional context, and formatting error information for display
 11 | /// or logging.
 12 | /// </summary>
 13 | public class Error : Reason
 14 | {
 15 |     /// <summary>
 16 |     /// Gets a default error instance with an empty message.
 17 |     /// </summary>
 18 |     public static Error Default => new("");
 19 | 
 20 |     /// <summary>
 21 |     /// Gets the list of errors that describe the reasons for the current failure or invalid state.
 22 |     /// </summary>
 23 |     public List<Error> Reasons { get; }
 24 | 
 25 |     private Error()
 26 |     {
 27 |         Reasons = [];
 28 |     }
 29 | 
 30 |     /// <summary>
 31 |     /// Initializes a new instance of the <see cref="Error"/> class with the specified message.
 32 |     /// </summary>
 33 |     /// <param name="message">The error message.</param>
 34 |     protected Error(string message) : this()
 35 |     {
 36 |         Message = message;
 37 |     }
 38 | 
 39 |     private Error(string message, Error causedBy) : this(message)
 40 |     {
 41 |         Reasons.Add(causedBy);
 42 |     }
 43 | 
 44 |     /// <summary>
 45 |     /// Creates a new <see cref="Error"/> instance with the specified message.
 46 |     /// </summary>
 47 |     /// <param name="message">The error message.</param>
 48 |     public static Error Create(string message)
 49 |     {
 50 |         return new Error(message);
 51 |     }
 52 | 
 53 |     /// <summary>
 54 |     /// Creates a new <see cref="Error"/> instance with the specified message and the <see cref="Error"/> instance that caused this error.
 55 |     /// </summary>
 56 |     /// <param name="message">The error message that describes the error.</param>
 57 |     /// <param name="causedBy">The underlying <see cref="Error"/> that caused this error.</param>
 58 |     public static Error Create(string message, Error causedBy)
 59 |     {
 60 |         return new Error(message, causedBy);
 61 |     }
 62 | 
 63 |     /// <summary>
 64 |     /// Adds the error reason that led to the current error and returns the updated error instance.
 65 |     /// </summary>
 66 |     /// <param name="message">The message of the error that led to this error.</param>
 67 |     public Error CausedBy(string message)
 68 |     {
 69 |         Reasons.Add(new Error(message));
 70 | 
 71 |         return this;
 72 |     }
 73 | 
 74 |     /// <summary>
 75 |     /// Adds the <see cref="Error"/> instance that led to the current error and returns the updated error instance.
 76 |     /// </summary>
 77 |     /// <param name="error">The <see cref="Error"/> instance that led to this error.</param>
 78 |     public Error CausedBy(Error error)
 79 |     {
 80 |         Reasons.Add(error);
 81 | 
 82 |         return this;
 83 |     }
 84 | 
 85 |     /// <summary>
 86 |     /// Adds the error reason from the specified empty optional value that led to the current error and returns the updated error instance.
 87 |     /// </summary>
 88 |     /// <typeparam name="TValue">The type of the value contained in the optional parameter.</typeparam>
 89 |     /// <param name="none">An optional value whose associated error reason will be added if present. Must be empty.</param>
 90 |     /// <returns>The current <see cref="Error"/> instance with the error reason added if the optional value is empty.</returns>
 91 |     /// <exception cref="InvalidOperationException">Thrown if <paramref name="none"/> does not have a value.</exception>
 92 |     public Error CausedBy<TValue>(Option<TValue> none)
 93 |     {
 94 |         if (none.HasValue)
 95 |         {
 96 |             throw new InvalidOperationException("The optional value must be empty in order to access its error object");
 97 |         }
 98 | 
 99 |         none.MatchNone(e => Reasons.Add(e));
100 | 
101 |         return this;
102 |     }
103 | 
104 |     /// <summary>
105 |     /// Adds the error reason from an unsuccessful <see cref="Option"/> to the current <see cref="Error"/> instance.
106 |     /// </summary>
107 |     /// <param name="none">The <see cref="Option"/> instance whose error reason will be added. Must represent an unsuccessful outcome.</param>
108 |     /// <returns>The current <see cref="Error"/> instance with the additional error reason included.</returns>
109 |     /// <exception cref="InvalidOperationException">Thrown if <paramref name="none"/> represents a successful outcome.</exception>
110 |     public Error CausedBy(Option none)
111 |     {
112 |         if (none.IsSuccessful)
113 |         {
114 |             throw new InvalidOperationException("The optional's outcome must be unsuccessful in order to access its error object");
115 |         }
116 | 
117 |         none.MatchNone(e => Reasons.Add(e));
118 | 
119 |         return this;
120 |     }
121 | 
122 |     /// <summary>
123 |     /// Adds the exception that led to the current error and returns the updated error instance.
124 |     /// </summary>
125 |     /// <param name="exception">The exception that caused or contributed to this error.</param>
126 |     public Error CausedBy(Exception exception)
127 |     {
128 |         Reasons.Add(ExceptionalError.Create(exception));
129 | 
130 |         return this;
131 |     }
132 | 
133 |     /// <summary>
134 |     /// Adds the specified metadata to the <see cref="Error"/> instance and returns the updated instance.
135 |     /// </summary>
136 |     /// <param name="name">The name of the metadata entry to add.</param>
137 |     /// <param name="value">The value to associate with the specified metadata name.</param>
138 |     public Error WithMetadata(string name, object value)
139 |     {
140 |         Metadata.Add(name, value);
141 | 
142 |         return this;
143 |     }
144 | 
145 |     /// <summary>
146 |     /// Adds the specified metadata entries to this <see cref="Error"/> instance and returns the updated instance.
147 |     /// </summary>
148 |     /// <param name="metadata">A dictionary containing metadata key-value pairs to add.</param>
149 |     public Error WithMetadata(Dictionary<string, object> metadata)
150 |     {
151 |         foreach (var metadataItem in metadata)
152 |         {
153 |             Metadata.Add(metadataItem.Key, metadataItem.Value);
154 |         }
155 | 
156 |         return this;
157 |     }
158 | 
159 |     /// <summary>
160 |     /// Adds metadata about the calling method's source location to the current <see cref="Error"/> instance and returns the updated instance.
161 |     /// </summary>
162 |     /// <remarks>This method is intended to be called without specifying arguments, so that the compiler automatically provides the caller's file path, method name, and line number using caller information attributes. This metadata can be useful for debugging or logging purposes.</remarks>
163 |     /// <param name="callingClassFilepath">The full file path of the source code file containing the calling method. This value is automatically supplied by the compiler and should not be set explicitly.</param>
164 |     /// <param name="callingMethod">The name of the calling method. This value is automatically supplied by the compiler and should not be set explicitly.</param>
165 |     /// <param name="callingClassLineNumber">The line number in the source file at which the method is called. This value is automatically supplied by the compiler and should not be set explicitly.</param>
166 |     public Error WithCallerMethodMetadata([CallerFilePath] string callingClassFilepath = "", [CallerMemberName] string callingMethod = "", [CallerLineNumber] int callingClassLineNumber = 0)
167 |     {
168 |         Metadata.Add(callingClassFilepath, $"{callingMethod}:{callingClassLineNumber}");
169 | 
170 |         return this;
171 |     }
172 | 
173 |     /// <summary>
174 |     /// Implicitly converts a string message to an <see cref="Error"/> instance.
175 |     /// </summary>
176 |     /// <param name="message">The error message.</param>
177 |     public static implicit operator Error(string message)
178 |     {
179 |         return Create(message);
180 |     }
181 | 
182 |     /// <summary>
183 |     /// Formats the error object as a one-line string, using the → symbol as a separator and an infinite depth.
184 |     /// </summary>
185 |     public string Print() => Print(0);
186 | 
187 |     /// <summary>
188 |     /// Formats the error object as a one-line string, using the specified symbol as a separator and an infinite depth.
189 |     /// </summary>
190 |     /// <param name="separator">A string to delimit the indivudual error messages with.</param>
191 |     public string Print(string separator)
192 |     {
193 |         var errorMessageChain = GetErrorMessageChain(this);
194 | 
195 |         return string.Join(separator, errorMessageChain);
196 |     }
197 | 
198 |     /// <summary>
199 |     /// Formats the error object as a one-line string, using the → symbol as a separator and using the specified depth value.
200 |     /// </summary>
201 |     /// <param name="depth">The number of levels to traverse in the error chain. Zero means infinite depth.</param>
202 |     public string Print(byte depth) => Print(null as Func<string, string>, depth);
203 | 
204 |     /// <summary>
205 |     /// Formats the error object as a one-line string using the specified transformation function on each individual message.
206 |     /// </summary>
207 |     /// <param name="transformFunc">A function to transform each message according to.</param>
208 |     /// <param name="depth">The number of levels to traverse in the error chain. Zero means infinite depth.</param>
209 |     /// <param name="separator">A string to delimit the indivudual error messages with.</param>
210 |     public string Print(Func<string, string> transformFunc, byte depth = 0, string separator = " → ")
211 |     {
212 |         transformFunc ??= s => s;
213 | 
214 |         var errorMessageChain = GetErrorMessageChain(this, depth).Select(transformFunc);
215 | 
216 |         return string.Join(separator, errorMessageChain);
217 |     }
218 | 
219 |     /// <summary>
220 |     /// Formats the error object as a one-line string using the specified transformation function on each individual message.
221 |     /// </summary>
222 |     /// <param name="transformFunc">A function to transform each message according to. <para>The second argument specifies the zero-based index of the message in the error chain and the third argument is <see langword="true"/> when the message is the last one in the chain.</para></param>
223 |     /// <param name="depth">The number of levels to traverse in the error chain. Zero means infinite depth.</param>
224 |     /// <param name="separator">A string to delimit the indivudual error messages with.</param>
225 |     public string Print(Func<string, int, bool, string> transformFunc, byte depth = 0, string separator = " → ")
226 |     {
227 |         transformFunc ??= (m, _, _) => m;
228 | 
229 |         var errorMessageChain = GetErrorMessageChain(this, depth).ToList();
230 | 
231 |         return string.Join(separator, errorMessageChain.Select((m, i) => transformFunc(m, i, i == errorMessageChain.Count - 1)));
232 |     }
233 | 
234 |     private static IEnumerable<string> GetErrorMessageChain(Error error, byte depth = 0)
235 |     {
236 |         var currentDepth = 0;
237 | 
238 |         while (true)
239 |         {
240 |             if (error == null || depth > 0 && currentDepth == depth)
241 |             {
242 |                 yield break;
243 |             }
244 | 
245 |             yield return error.Message;
246 | 
247 |             error = error.Reasons.FirstOrDefault();
248 | 
249 |             currentDepth++;
250 |         }
251 |     }
252 | 
253 |     /// <inheritdoc/>
254 |     protected internal override ReasonStringBuilder GetReasonStringBuilder()
255 |     {
256 |         return new ReasonStringBuilder().WithInfo("", Message)
257 |                                         .WithInfoNoQuotes(nameof(Metadata), string.Join("; ", Metadata.Select(kvp => $"{kvp.Key}: {kvp.Value}")))
258 |                                         .WithInfoNoQuotes("Caused by", $"{string.Join(" ⁎ ", Reasons)}");
259 |     }
260 | }
261 | 


--------------------------------------------------------------------------------
/src/OptionExtensions.cs:
--------------------------------------------------------------------------------
  1 | namespace Ultimately;
  2 | 
  3 | using Reasons;
  4 | 
  5 | using System;
  6 | 
  7 | /// <summary>
  8 | /// Provides extension methods for creating and transforming optional values.
  9 | /// </summary>
 10 | public static class OptionExtensions
 11 | {
 12 |     /// <summary>
 13 |     /// Wraps an existing value in an <see cref="Option{TValue}"/> instance.
 14 |     /// </summary>
 15 |     /// <param name="value">The value to be wrapped.</param>
 16 |     /// <returns>An optional containing the specified value.</returns>
 17 |     public static Option<TValue> Some<TValue>(this TValue value) => Optional.Some(value);
 18 | 
 19 |     /// <summary>
 20 |     /// Wraps an existing value in an <see cref="Option{TValue}"/> instance with a specified success message.
 21 |     /// </summary>
 22 |     /// <param name="value">The value to be wrapped.</param>
 23 |     /// <param name="successMessage">A message describing the reason or origin behind the presence of the optional value.</param>
 24 |     /// <returns>An optional containing the specified value.</returns>
 25 |     public static Option<TValue> Some<TValue>(this TValue value, string successMessage) => Optional.Some(value, successMessage);
 26 | 
 27 |     /// <summary>
 28 |     /// Wraps an existing value in an <see cref="Option{TValue}"/> instance with a specified success object.
 29 |     /// </summary>
 30 |     /// <param name="value">The value to be wrapped.</param>
 31 |     /// <param name="success">An object describing the reason or origin behind the presence of the optional value.</param>
 32 |     /// <returns>An optional containing the specified value.</returns>
 33 |     public static Option<TValue> Some<TValue>(this TValue value, Success success) => Optional.Some(value, success);
 34 | 
 35 |     /// <summary>
 36 |     /// Creates an <see cref="Option{TValue}"/> instance from a specified value.
 37 |     /// <para>If the value does not satisfy the given predicate, an empty optional is returned with the specified error object.</para>
 38 |     /// </summary>
 39 |     /// <param name="value">The value to wrap.</param>
 40 |     /// <param name="predicate">The predicate to satisfy.</param>
 41 |     /// <param name="error">An error object describing why the optional is missing its value.</param>
 42 |     /// <returns>An optional containing the specified value, if the predicate is satisified.</returns>
 43 |     public static Option<TValue> SomeWhen<TValue>(this TValue value, Predicate<TValue> predicate, Error error)
 44 |     {
 45 |         ArgumentNullException.ThrowIfNull(predicate);
 46 | 
 47 |         return predicate(value) ? Optional.Some(value) : Optional.None<TValue>(error);
 48 |     }
 49 | 
 50 |     /// <summary>
 51 |     /// Creates an <see cref="Option{TValue}"/> instance from a specified value and success message.
 52 |     /// <para>If the value does not satisfy the given predicate, an empty optional is returned with the specified error message.</para>
 53 |     /// </summary>
 54 |     /// <param name="value">The value to wrap.</param>
 55 |     /// <param name="predicate">The predicate to satisfy.</param>
 56 |     /// <param name="successMessage">A message describing the reason or origin behind the presence of the optional value.</param>
 57 |     /// <param name="errorMessage">A description of why the optional is missing its value if the predicate is not satisfied.</param>
 58 |     /// <returns>An optional containing the specified value, if the predicate is satisified.</returns>
 59 |     public static Option<TValue> SomeWhen<TValue>(this TValue value, Predicate<TValue> predicate, string successMessage, string errorMessage)
 60 |     {
 61 |         ArgumentNullException.ThrowIfNull(predicate);
 62 | 
 63 |         return predicate(value) ? Optional.Some(value, successMessage) : Optional.None<TValue>(errorMessage);
 64 |     }
 65 | 
 66 |     /// <summary>
 67 |     /// Creates an <see cref="Option{TValue}"/> instance from a specified value and success object.
 68 |     /// <para>If the value does not satisfy the given predicate, an empty optional is returned with the specified error object.</para>
 69 |     /// </summary>
 70 |     /// <param name="value">The value to wrap.</param>
 71 |     /// <param name="predicate">The predicate to satisfy.</param>
 72 |     /// <param name="success">An object with data describing the reason or origin behind the presence of the optional value.</param>
 73 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
 74 |     /// <returns>An optional containing the specified value, if the predicate is satisified.</returns>
 75 |     public static Option<TValue> SomeWhen<TValue>(this TValue value, Predicate<TValue> predicate, Success success, Error error)
 76 |     {
 77 |         ArgumentNullException.ThrowIfNull(predicate);
 78 | 
 79 |         return predicate(value) ? Optional.Some(value, success) : Optional.None<TValue>(error);
 80 |     }
 81 | 
 82 |     /// <summary>
 83 |     /// Creates an <see cref="Option{TValue}"/> instance from a specified value.
 84 |     /// <para>If the value satisfies the given predicate, an empty optional is returned with the specified error object attached.</para>
 85 |     /// </summary>
 86 |     /// <param name="value">The value to wrap.</param>
 87 |     /// <param name="predicate">The predicate.</param>
 88 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
 89 |     /// <returns>An optional containing the specified value, if the predicate is not satisifed.</returns>
 90 |     public static Option<TValue> NoneWhen<TValue>(this TValue value, Predicate<TValue> predicate, Error error)
 91 |     {
 92 |         ArgumentNullException.ThrowIfNull(predicate);
 93 | 
 94 |         return value.SomeWhen(val => !predicate(val), error);
 95 |     }
 96 | 
 97 |     /// <summary>
 98 |     /// Creates an <see cref="Option{TValue}"/> instance from a specified value.
 99 |     /// <para>If the value is null, an empty optional is returned with the specified error object attached.</para>
100 |     /// </summary>
101 |     /// <param name="value">The value to wrap.</param>
102 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
103 |     /// <returns>An optional containing the specified value given that it's not null.</returns>
104 |     public static Option<TValue> SomeNotNull<TValue>(this TValue value, Error error) => value.SomeWhen(val => val != null, error);
105 | 
106 |     /// <summary>
107 |     /// Converts a <see cref="Nullable{T}"/> to an <see cref="Option{TValue}"/> instance with the specified error message if its value is null.
108 |     /// <para>If its value is null, an empty optional is returned with the specified error object attached.</para>
109 |     /// </summary>
110 |     /// <param name="value">The Nullable&lt;T&gt; instance.</param>
111 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
112 |     /// <returns>The <see cref="Option{TValue}"/> instance.</returns>
113 |     public static Option<TValue> ToOption<TValue>(this TValue? value, Error error)
114 |         where TValue : struct
115 |         => value.HasValue ? Optional.Some(value.Value) : Optional.None<TValue>(error);
116 | 
117 |     /// <summary>
118 |     /// Flattens two nested optionals into one. The resulting optional will be empty if either the inner or outer optional is empty.
119 |     /// </summary>
120 |     /// <param name="nestedOption">The nested optional.</param>
121 |     /// <returns>A flattened optional.</returns>
122 |     public static Option<TValue> Flatten<TValue>(this Option<Option<TValue>> nestedOption) => nestedOption.FlatMap(innerOption => innerOption);
123 | 
124 |     /// <summary>
125 |     /// Transforms the optional into an optional with a value. The result is flattened, and if the original optional's outcome is unsuccessful, an empty optional is returned.
126 |     /// </summary>
127 |     /// <param name="option">The optional to transform.</param>
128 |     /// <param name="mapping">The transformation function.</param>
129 |     /// <param name="subsequentError">If the resulting optional is empty, sets its error as the direct reason to the specified subsequent error.</param>
130 |     /// <returns>The transformed optional.</returns>
131 |     public static Option<TResult> Map<TResult>(this Option option, Func<TResult> mapping, Error subsequentError = null)
132 |     {
133 |         ArgumentNullException.ThrowIfNull(mapping);
134 | 
135 |         Func<Error, Option<TResult>> errorFunc = Optional.None<TResult>;
136 | 
137 |         if (subsequentError != null)
138 |         {
139 |             errorFunc = e => Optional.None<TResult>(subsequentError.CausedBy(e));
140 |         }
141 | 
142 |         return option.Match(
143 |                             some: s => Optional.Some(mapping(), s),
144 |                             none: errorFunc
145 |                            );
146 |     }
147 | 
148 |     /// <summary>
149 |     /// Transforms the optional into an optional with a value. The result is flattened, and if the original optional's outcome is unsuccessful, an empty optional is returned.
150 |     /// </summary>
151 |     /// <param name="option">The optional to transform.</param>
152 |     /// <param name="mapping">The transformation function.</param>
153 |     /// <param name="subsequentError">If the resulting optional is empty, sets its error as the direct reason to the specified subsequent error.<para>Example: "Failed to create object" (child error), Caused by: "Timed out while connecting to service" (antecedent optional with an unsuccessful outcome)</para></param>
154 |     /// <returns>The transformed optional.</returns>
155 |     public static Option<TResult> Map<TResult>(this Option option, Func<Success, TResult> mapping, Error subsequentError = null)
156 |     {
157 |         ArgumentNullException.ThrowIfNull(mapping);
158 | 
159 |         Func<Error, Option<TResult>> errorFunc = Optional.None<TResult>;
160 | 
161 |         if (subsequentError != null)
162 |         {
163 |             errorFunc = e => Optional.None<TResult>(subsequentError.CausedBy(e));
164 |         }
165 | 
166 |         return option.Match(
167 |                             some: s => Optional.Some(mapping(s), s),
168 |                             none: errorFunc
169 |                            );
170 |     }
171 | 
172 |     /// <summary>
173 |     /// Transforms the optional into an optional with a value. The result is flattened, and if either optional's outcome is unsuccessful, an empty optional is returned.
174 |     /// </summary>
175 |     /// <param name="option">The optional to transform.</param>
176 |     /// <param name="mapping">The transformation function.</param>
177 |     /// <param name="subsequentError">If the resulting optional is empty, sets its error as the direct reason to the specified subsequent error.</param>
178 |     /// <returns>The transformed optional.</returns>
179 |     public static Option<TResult> FlatMap<TResult>(this Option option, Func<Option<TResult>> mapping, Error subsequentError = null)
180 |     {
181 |         ArgumentNullException.ThrowIfNull(mapping);
182 | 
183 |         Option<TResult> result;
184 | 
185 |         if (option.IsSuccessful)
186 |         {
187 |             result = mapping();
188 | 
189 |             result.MatchNone(e =>
190 |             {
191 |                 if (subsequentError != null)
192 |                 {
193 |                     result = Optional.None<TResult>(subsequentError.CausedBy(e));
194 |                 }
195 |             });
196 |         }
197 |         else
198 |         {
199 |             result = Optional.None<TResult>(subsequentError != null ? subsequentError.CausedBy(option.Error) : option.Error);
200 |         }
201 | 
202 |         return result;
203 |     }
204 | 
205 |     /// <summary>
206 |     /// Transforms the optional into an optional with a value. The result is flattened, and if either optional's outcome is unsuccessful, an empty optional is returned.
207 |     /// </summary>
208 |     /// <param name="option">The optional to transform.</param>
209 |     /// <param name="mapping">The transformation function.</param>
210 |     /// <param name="subsequentError">If the resulting optional is empty, sets its error as the direct reason to the specified subsequent error.</param>
211 |     /// <returns>The transformed optional.</returns>
212 |     public static Option<TResult> FlatMap<TResult>(this Option option, Func<Success, Option<TResult>> mapping, Error subsequentError = null)
213 |     {
214 |         ArgumentNullException.ThrowIfNull(mapping);
215 | 
216 |         Option<TResult> result;
217 | 
218 |         if (option.IsSuccessful)
219 |         {
220 |             result = mapping(option.Success);
221 | 
222 |             result.MatchNone(e =>
223 |             {
224 |                 if (subsequentError != null)
225 |                 {
226 |                     result = Optional.None<TResult>(subsequentError.CausedBy(e));
227 |                 }
228 |             });
229 |         }
230 |         else
231 |         {
232 |             result = Optional.None<TResult>(subsequentError != null ? subsequentError.CausedBy(option.Error) : option.Error);
233 |         }
234 | 
235 |         return result;
236 |     }
237 | 
238 |     /// <summary>
239 |     /// Transforms the value-optional into an optional with an outcome. The result is flattened, and if either the source optional is empty or the resulting optional's outcome is unsuccessful, an optional with an unsuccessful outcome is returned.
240 |     /// </summary>
241 |     /// <param name="option">The optional to transform.</param>
242 |     /// <param name="mapping">The transformation function.</param>
243 |     /// <param name="subsequentError">If the resulting optional is empty, sets its error as the direct reason to the specified subsequent error.</param>
244 |     /// <returns>The transformed optional.</returns>
245 |     public static Option FlatMap<TValue>(this Option<TValue> option, Func<TValue, Option> mapping, Error subsequentError = null)
246 |     {
247 |         ArgumentNullException.ThrowIfNull(mapping);
248 | 
249 |         Option result;
250 | 
251 |         if (option.HasValue)
252 |         {
253 |             result = mapping(option.Value);
254 | 
255 |             result.MatchNone(e =>
256 |             {
257 |                 if (subsequentError != null)
258 |                 {
259 |                     result = Optional.None(subsequentError.CausedBy(e));
260 |                 }
261 |             });
262 |         }
263 |         else
264 |         {
265 |             result = Optional.None(subsequentError != null ? subsequentError.CausedBy(option.Error) : option.Error);
266 |         }
267 | 
268 |         return result;
269 |     }
270 | 
271 |     /// <summary>
272 |     /// Transforms the value-optional into an optional with an outcome. The result is flattened, and if either the source optional is empty or the resulting optional's outcome is unsuccessful, an optional with an unsuccessful outcome is returned.
273 |     /// </summary>
274 |     /// <param name="option">The optional to transform.</param>
275 |     /// <param name="mapping">The transformation function.</param>
276 |     /// <param name="subsequentError">If the resulting optional is empty, sets its error as the direct reason to the specified subsequent error.</param>
277 |     /// <returns>The transformed optional.</returns>
278 |     public static Option FlatMap<TValue>(this Option<TValue> option, Func<TValue, Success, Option> mapping, Error subsequentError = null)
279 |     {
280 |         ArgumentNullException.ThrowIfNull(mapping);
281 | 
282 |         Option result;
283 | 
284 |         if (option.HasValue)
285 |         {
286 |             result = mapping(option.Value, option.Success);
287 | 
288 |             result.MatchNone(e =>
289 |             {
290 |                 if (subsequentError != null)
291 |                 {
292 |                     result = Optional.None(subsequentError.CausedBy(e));
293 |                 }
294 |             });
295 |         }
296 |         else
297 |         {
298 |             result = Optional.None(subsequentError != null ? subsequentError.CausedBy(option.Error) : option.Error);
299 |         }
300 | 
301 |         return result;
302 |     }
303 | }
304 | 


--------------------------------------------------------------------------------
/src/Optional.cs:
--------------------------------------------------------------------------------
  1 | namespace Ultimately;
  2 | 
  3 | using Reasons;
  4 | 
  5 | using System;
  6 | using System.Threading.Tasks;
  7 | 
  8 | /// <summary>
  9 | /// Provides a set of methods for creating optional values.
 10 | /// </summary>
 11 | public static class Optional
 12 | {
 13 |     /// <summary>
 14 |     /// Creates an optional with a successful outcome.
 15 |     /// </summary>
 16 |     /// <returns>An optional with a successful outcome.</returns>
 17 |     public static Option Some() => Some(Success.Default);
 18 | 
 19 |     /// <summary>
 20 |     /// Creates an optional with a successful outcome.
 21 |     /// </summary>
 22 |     /// <param name="success">A success object with data describing the successful outcome.</param>
 23 |     /// <returns>An optional with a successful outcome.</returns>
 24 |     public static Option Some(Success success) => new(true, success, null);
 25 | 
 26 |     /// <summary>
 27 |     /// Creates an optional with a successful outcome by using the success object of the specified optional with a value.
 28 |     /// <para>The provided optional cannot be empty.</para>
 29 |     /// </summary>
 30 |     /// <param name="some">An optional with a value whose success object to copy.</param>
 31 |     /// <returns>An optional containing the specified value.</returns>
 32 |     public static Option Some<TResult>(Option<TResult> some)
 33 |     {
 34 |         if (!some.HasValue)
 35 |         {
 36 |             throw new ArgumentException("Source optional must have a value");
 37 |         }
 38 | 
 39 |         return new Option(true, some.Success, null);
 40 |     }
 41 | 
 42 |     /// <summary>
 43 |     /// Creates an optional with an unsuccessful outcome.
 44 |     /// </summary>
 45 |     /// <param name="message">A description of the error that caused the unsuccessful outcome.</param>
 46 |     /// <returns>An optional with an unsuccessful outcome.</returns>
 47 |     public static Option None(string message) => None(Error.Create(message));
 48 | 
 49 |     /// <summary>
 50 |     /// Creates an optional with an unsuccessful outcome.
 51 |     /// </summary>
 52 |     /// <param name="message">A description of the error that caused the unsuccessful outcome.</param>
 53 |     /// <param name="exception">An exception instance to attach to the error property of the unsuccessful optional.</param>
 54 |     /// <returns>An optional with an unsuccessful outcome.</returns>
 55 |     public static Option None(string message, Exception exception) => None(Error.Create(message).CausedBy(exception));
 56 | 
 57 |     /// <summary>
 58 |     /// Creates an optional with an unsuccessful outcome from an exception.
 59 |     /// </summary>
 60 |     /// <param name="exception">An exception instance to create an optional with an unsuccessful outcome from.</param>
 61 |     /// <returns>An optional with an unsuccessful outcome.</returns>
 62 |     public static Option None(Exception exception) => None(ExceptionalError.Create(exception));
 63 | 
 64 |     /// <summary>
 65 |     /// Creates an optional with an unsuccessful outcome.
 66 |     /// </summary>
 67 |     /// <param name="error">An error object with data describing what caused the unsuccessful outcome.</param>
 68 |     /// <returns>An optional with an unsuccessful outcome.</returns>
 69 |     public static Option None(Error error) => new(false, null, error);
 70 | 
 71 |     /// <summary>
 72 |     /// Creates an optional with an unsuccessful outcome by using the error object of an empty optional.
 73 |     /// </summary>
 74 |     /// <param name="none">An empty optional whose error object to copy.</param>
 75 |     /// <returns>An optional with an unsuccessful outcome based on the specified empty optional.</returns>
 76 |     public static Option None<TValue>(Option<TValue> none)
 77 |     {
 78 |         if (none.HasValue)
 79 |         {
 80 |             throw new ArgumentException("Source optional must be empty");
 81 |         }
 82 | 
 83 |         return new Option(false, null, none.Error);
 84 |     }
 85 | 
 86 |     /// <summary>
 87 |     /// Creates an <see cref="Option"/> instance whose outcome depends on the satisfaction of the given predicate.
 88 |     /// <para>If the predicate evaluates to false, an empty optional is returned with the specified error object.</para>
 89 |     /// </summary>
 90 |     /// <param name="predicate">The predicate to satisfy.</param>
 91 |     /// <param name="error">An error object to attach to the optional when its outcome is unsuccessful.</param>
 92 |     /// <returns>An optional whose outcome depends on the satisfaction of the provided predicate.</returns>
 93 |     public static Option SomeWhen(bool predicate, Error error)
 94 |     {
 95 |         return predicate ? Some() : None(error);
 96 |     }
 97 | 
 98 |     /// <summary>
 99 |     /// Creates an <see cref="Option"/> instance whose outcome depends on the satisfaction of the given predicate.
100 |     /// <para>If the predicate evaluates to true, an empty optional is returned with the specified error object.</para>
101 |     /// </summary>
102 |     /// <param name="predicate">The predicate to satisfy.</param>
103 |     /// <param name="error">An error object with data describing what caused the unsuccessful outcome.</param>
104 |     /// <returns>An optional whose outcome depends on the satisfaction of the provided predicate.</returns>
105 |     public static Option NoneWhen(bool predicate, Error error)
106 |     {
107 |         return !predicate ? Some() : None(error);
108 |     }
109 | 
110 |     /// <summary>
111 |     /// Creates an <see cref="Option"/> instance whose outcome depends on the satisfaction of the given predicate.
112 |     /// <para>If the predicate evaluates to false, an empty optional is returned with the specified error object.</para>
113 |     /// </summary>
114 |     /// <param name="predicate">The predicate to satisfy.</param>
115 |     /// <param name="success">A success object with data describing the successful outcome.</param>
116 |     /// <param name="error">An error object to attach to the optional when its outcome is unsuccessful.</param>
117 |     /// <returns>An optional whose outcome depends on the satisfaction of the provided predicate.</returns>
118 |     public static Option SomeWhen(bool predicate, Success success, Error error)
119 |     {
120 |         return predicate ? Some(success) : None(error);
121 |     }
122 | 
123 |     /// <summary>
124 |     /// Creates an <see cref="Option"/> instance whose outcome depends on the satisfaction of the given predicate.
125 |     /// <para>If the predicate evaluates to true, an empty optional is returned with the specified error object.</para>
126 |     /// </summary>
127 |     /// <param name="predicate">The predicate to satisfy.</param>
128 |     /// <param name="success">A success object with data describing the successful outcome.</param>
129 |     /// <param name="error">An error object with data describing what caused the unsuccessful outcome.</param>
130 |     /// <returns>An optional whose outcome depends on the satisfaction of the provided predicate.</returns>
131 |     public static Option NoneWhen(bool predicate, Success success, Error error)
132 |     {
133 |         return !predicate ? Some(success) : None(error);
134 |     }
135 | 
136 | 
137 | 
138 |     /// <summary>
139 |     /// Wraps an existing value in an <see cref="Option{T}"/> instance.
140 |     /// </summary>
141 |     /// <param name="value">The value to be wrapped.</param>
142 |     /// <returns>An optional containing the specified value.</returns>
143 |     public static Option<TValue> Some<TValue>(TValue value) => new(true, value, Success.Default, null);
144 | 
145 |     /// <summary>
146 |     /// Wraps an existing value in an <see cref="Option{T}"/> instance with a specified success message.
147 |     /// </summary>
148 |     /// <param name="value">The value to be wrapped.</param>
149 |     /// <param name="successMessage">A message describing the reason or origin behind the presence of the optional value.</param>
150 |     /// <returns>An optional containing the specified value.</returns>
151 |     public static Option<TValue> Some<TValue>(TValue value, string successMessage) => new(true, value, Success.Create(successMessage), null);
152 | 
153 |     /// <summary>
154 |     /// Wraps an existing value in an <see cref="Option{T}"/> instance with a specified success object.
155 |     /// </summary>
156 |     /// <param name="value">The value to be wrapped.</param>
157 |     /// <param name="success">An object with data describing the reason or origin behind the presence of the optional value.</param>
158 |     /// <returns>An optional containing the specified value.</returns>
159 |     public static Option<TValue> Some<TValue>(TValue value, Success success) => new(true, value, success, null);
160 | 
161 |     /// <summary>
162 |     /// Wraps an existing value in an <see cref="Option{T}"/> instance with the success object of the specified optional.
163 |     /// <para>The outcome of the provided optional must be successful.</para>
164 |     /// </summary>
165 |     /// <param name="value">The value to be wrapped.</param>
166 |     /// <param name="some">A successful optional whose success object to copy.</param>
167 |     /// <returns>An optional containing the specified value.</returns>
168 |     public static Option<TValue> Some<TValue>(TValue value, Option some)
169 |     {
170 |         if (!some.IsSuccessful)
171 |         {
172 |             throw new ArgumentException("Source optional must be successful");
173 |         }
174 | 
175 |         return new Option<TValue>(true, value, some.Success, null);
176 |     }
177 | 
178 |     /// <summary>
179 |     /// Wraps an existing value in an <see cref="Option{T}"/> instance with the success object of the specified optional.
180 |     /// <para>The provided optional cannot be empty.</para>
181 |     /// </summary>
182 |     /// <param name="value">The value to be wrapped.</param>
183 |     /// <param name="some">An optional with a value whose success object to copy.</param>
184 |     /// <returns>An optional containing the specified value.</returns>
185 |     public static Option<TValue> Some<TValue, TResult>(TValue value, Option<TResult> some)
186 |     {
187 |         if (!some.HasValue)
188 |         {
189 |             throw new ArgumentException("Source optional must have a value");
190 |         }
191 | 
192 |         return new Option<TValue>(true, value, some.Success, null);
193 |     }
194 | 
195 |     /// <summary>
196 |     /// Creates an empty <see cref="Option{TValue}"/> instance with a specified error message.
197 |     /// </summary>
198 |     /// <param name="message">A description of why the optional is missing its value.</param>
199 |     /// <returns>An empty optional.</returns>
200 |     public static Option<TValue> None<TValue>(string message) => None<TValue>(Error.Create(message));
201 | 
202 |     /// <summary>
203 |     /// Creates an empty <see cref="Option{TValue}"/> instance with a specified error message and exception.
204 |     /// </summary>
205 |     /// <param name="message">A description of why the optional is missing its value.</param>
206 |     /// <param name="exception">An exception instance to attach to error property of the empty optional.</param>
207 |     /// <returns>An empty optional.</returns>
208 |     public static Option<TValue> None<TValue>(string message, Exception exception) => None<TValue>(Error.Create(message).CausedBy(exception));
209 | 
210 |     /// <summary>
211 |     /// Creates an empty <see cref="Option{TValue}"/> instance with the specified exception.
212 |     /// </summary>
213 |     /// <param name="exception">An exception instance to create an empty optional from.</param>
214 |     /// <returns>An empty optional.</returns>
215 |     public static Option<TValue> None<TValue>(Exception exception) => None<TValue>(ExceptionalError.Create(exception));
216 | 
217 |     /// <summary>
218 |     /// Creates an empty <see cref="Option{TValue}"/> instance with a specified error object.
219 |     /// </summary>
220 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
221 |     /// <returns>An empty optional.</returns>
222 |     public static Option<TValue> None<TValue>(Error error) => new(false, default, null, error);
223 | 
224 |     /// <summary>
225 |     /// Creates an empty optional with the error object of an optional with an unsuccessful outcome.
226 |     /// </summary>
227 |     /// <param name="none">An empty optional whose error object to copy.</param>
228 |     /// <returns>An empty optional based on the specified optional with an unsuccessful outcome.</returns>
229 |     public static Option<TValue> None<TValue>(Option none)
230 |     {
231 |         if (none.IsSuccessful)
232 |         {
233 |             throw new ArgumentException("Source optional must be unsuccessful");
234 |         }
235 | 
236 |         return new Option<TValue>(false, default, null, none.Error);
237 |     }
238 | 
239 |     /// <summary>
240 |     /// Creates a new empty optional with the error object of the specified empty optional.
241 |     /// </summary>
242 |     /// <param name="none">An empty optional whose error object to copy.</param>
243 |     /// <returns>An empty optional based on the specified empty optional.</returns>
244 |     public static Option<TResult> None<TValue, TResult>(Option<TValue> none)
245 |     {
246 |         if (none.HasValue)
247 |         {
248 |             throw new ArgumentException("Source optional must be empty");
249 |         }
250 | 
251 |         return new Option<TResult>(false, default, null, none.Error);
252 |     }
253 | 
254 | 
255 |     /// <summary>
256 |     /// Creates a <see cref="LazyOption"/> instance whose outcome depends on the satisfaction of the given predicate.
257 |     /// <para>When resolved, if the predicate evaluates to false, an empty optional is returned with the specified error object.</para>
258 |     /// </summary>
259 |     /// <param name="predicate">The predicate to satisfy.</param>
260 |     /// <param name="error">An error object to attach to the resolved optional in case its outcome is unsuccessful.</param>
261 |     /// <returns>A deferred optional whose outcome depends on the satisfaction of the provided predicate.</returns>
262 |     public static LazyOption Lazy(Func<bool> predicate, Error error)
263 |     {
264 |         return Lazy(predicate, Success.Default, error);
265 |     }
266 | 
267 |     /// <summary>
268 |     /// Creates a <see cref="LazyOption"/> instance whose outcome depends on the satisfaction of the given predicate.
269 |     /// <para>When resolved, if the predicate evaluates to false, an empty optional is returned with the specified error object.</para>
270 |     /// </summary>
271 |     /// <param name="predicate">The predicate to satisfy.</param>
272 |     /// <param name="success">A success object with data describing the successful outcome.</param>
273 |     /// <param name="error">An error object to attach to the resolved optional in case its outcome is unsuccessful.</param>
274 |     /// <returns>A deferred optional whose outcome depends on the satisfaction of the provided predicate.</returns>
275 |     public static LazyOption Lazy(Func<bool> predicate, Success success, Error error)
276 |     {
277 |         return new LazyOption(predicate, success, error);
278 |     }
279 | 
280 |     /// <summary>
281 |     /// Creates a <see cref="LazyOption"/> instance whose outcome depends on the satisfaction of the given predicate task.
282 |     /// <para>When resolved, if the predicate evaluates to false, an empty optional is returned with the specified error object.</para>
283 |     /// </summary>
284 |     /// <param name="predicateTask">The predicate to satisfy.</param>
285 |     /// <param name="error">An error object to attach to the resolved optional in case its outcome is unsuccessful.</param>
286 |     /// <returns>A deferred optional whose outcome depends on the satisfaction of the provided predicate.</returns>
287 |     public static LazyOptionAsync LazyAsync(Func<Task<bool>> predicateTask, Error error)
288 |     {
289 |         return new LazyOptionAsync(predicateTask, Success.Default, error);
290 |     }
291 | 
292 |     /// <summary>
293 |     /// Creates a <see cref="LazyOption"/> instance whose outcome depends on the satisfaction of the given predicate task.
294 |     /// <para>When resolved, if the predicate evaluates to false, an empty optional is returned with the specified error object.</para>
295 |     /// </summary>
296 |     /// <param name="predicateTask">The predicate to satisfy.</param>
297 |     /// <param name="success">A success object with data describing the successful outcome.</param>
298 |     /// <param name="error">An error object to attach to the resolved optional in case its outcome is unsuccessful.</param>
299 |     /// <returns>A deferred optional whose outcome depends on the satisfaction of the provided predicate.</returns>
300 |     public static LazyOptionAsync LazyAsync(Func<Task<bool>> predicateTask, Success success, Error error)
301 |     {
302 |         return new LazyOptionAsync(predicateTask, success, error);
303 |     }
304 | }
305 | 


--------------------------------------------------------------------------------
/src/Collections/OptionCollectionExtensions.cs:
--------------------------------------------------------------------------------
  1 | namespace Ultimately.Collections;
  2 | 
  3 | using Async;
  4 | using Reasons;
  5 | using Utilities;
  6 | 
  7 | using System;
  8 | using System.Collections.Generic;
  9 | using System.Linq;
 10 | using System.Threading.Tasks;
 11 | 
 12 | /// <summary>
 13 | /// Provides extension methods for working with collections of optionals, enabling safe retrieval, transformation, and
 14 | /// aggregation of values and errors from sequences that may contain missing or exceptional elements.
 15 | /// </summary>
 16 | public static class OptionCollectionExtensions
 17 | {
 18 | 
 19 |     /// <summary>
 20 |     /// Flattens a sequence of optionals into a sequence containing all inner values.
 21 |     /// Empty elements are discarded.
 22 |     /// </summary>
 23 |     /// <param name="source">The sequence of optionals.</param>
 24 |     /// <returns>A flattened sequence of values.</returns>
 25 |     public static IEnumerable<TValue> Values<TValue>(this IEnumerable<Option<TValue>> source)
 26 |     {
 27 |         ArgumentNullException.ThrowIfNull(source);
 28 | 
 29 |         foreach (var option in source)
 30 |         {
 31 |             if (option.HasValue)
 32 |             {
 33 |                 yield return option.Value;
 34 |             }
 35 |         }
 36 |     }
 37 | 
 38 |     /// <summary>
 39 |     /// Flattens a sequence of optionals into a sequence containing all exceptional values.
 40 |     /// Non-empty elements and their values are discarded.
 41 |     /// </summary>
 42 |     /// <param name="source">The sequence of optionals.</param>
 43 |     /// <returns>A flattened sequence of exceptional values.</returns>
 44 |     public static IEnumerable<Error> Errors<TValue>(this IEnumerable<Option<TValue>> source)
 45 |     {
 46 |         ArgumentNullException.ThrowIfNull(source);
 47 | 
 48 |         foreach (var option in source)
 49 |         {
 50 |             if (!option.HasValue)
 51 |             {
 52 |                 yield return option.Error;
 53 |             }
 54 |         }
 55 |     }
 56 | 
 57 |     /// <summary>
 58 |     /// Returns the value associated with the specified key if such exists.
 59 |     /// A dictionary lookup will be used if available, otherwise falling
 60 |     /// back to a linear scan of the enumerable.
 61 |     /// </summary>
 62 |     /// <param name="source">The dictionary or enumerable in which to locate the key.</param>
 63 |     /// <param name="key">The key to locate.</param>
 64 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
 65 |     /// <returns>An <see cref="Option{TValue}"/> instance containing the associated value if located.</returns>
 66 |     public static Option<TValue> GetValueOrNone<TKey, TValue>(this IEnumerable<KeyValuePair<TKey, TValue>> source, TKey key, Error error = null)
 67 |     {
 68 |         ArgumentNullException.ThrowIfNull(source);
 69 | 
 70 |         if (source is IDictionary<TKey, TValue> dictionary)
 71 |         {
 72 |             return dictionary.TryGetValue(key, out var value) ? value.Some() : Optional.None<TValue>(error ?? Error.Create(MissingReasons.KeyNotFound));
 73 |         }
 74 | 
 75 |         if (source is IReadOnlyDictionary<TKey, TValue> readOnlyDictionary)
 76 |         {
 77 |             return readOnlyDictionary.TryGetValue(key, out var value) ? value.Some() : Optional.None<TValue>(error ?? Error.Create(MissingReasons.KeyNotFound));
 78 |         }
 79 | 
 80 |         return source.FirstOrNone(pair => EqualityComparer<TKey>.Default.Equals(pair.Key, key), Error.Create(MissingReasons.KeyNotFoundIndexer))
 81 |                      .Map(pair => pair.Value);
 82 |     }
 83 | 
 84 |     /// <summary>
 85 |     /// Returns the first element of a sequence if such exists.
 86 |     /// </summary>
 87 |     /// <param name="source">The sequence to return the first element from.</param>
 88 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
 89 |     /// <returns>An <see cref="Option{TValue}"/> instance containing the first element if present.</returns>
 90 |     public static Option<TSource> FirstOrNone<TSource>(this IEnumerable<TSource> source, Error error = null)
 91 |     {
 92 |         ArgumentNullException.ThrowIfNull(source);
 93 | 
 94 |         if (source is IList<TSource> list)
 95 |         {
 96 |             if (list.Count > 0)
 97 |             {
 98 |                 return list[0].Some();
 99 |             }
100 |         }
101 |         else if (source is IReadOnlyList<TSource> readOnlyList)
102 |         {
103 |             if (readOnlyList.Count > 0)
104 |             {
105 |                 return readOnlyList[0].Some();
106 |             }
107 |         }
108 |         else
109 |         {
110 |             using var enumerator = source.GetEnumerator();
111 |             if (enumerator.MoveNext())
112 |             {
113 |                 return enumerator.Current.Some();
114 |             }
115 |         }
116 | 
117 |         return Optional.None<TSource>(error ?? Error.Create(MissingReasons.CollectionWasEmpty));
118 |     }
119 | 
120 |     /// <summary>
121 |     /// Returns the first element of a sequence, satisfying a specified predicate,
122 |     /// if such exists.
123 |     /// </summary>
124 |     /// <param name="source">The sequence to return the first element from.</param>
125 |     /// <param name="predicate">The predicate to filter by.</param>
126 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
127 |     /// <returns>An <see cref="Option{TValue}"/> instance containing the first element if present.</returns>
128 |     public static Option<TSource> FirstOrNone<TSource>(this IEnumerable<TSource> source, Predicate<TSource> predicate, Error error = null)
129 |     {
130 |         ArgumentNullException.ThrowIfNull(source);
131 | 
132 |         ArgumentNullException.ThrowIfNull(predicate);
133 | 
134 |         foreach (var element in source)
135 |         {
136 |             if (predicate(element))
137 |             {
138 |                 return element.Some();
139 |             }
140 |         }
141 | 
142 |         return Optional.None<TSource>(error ?? Error.Create(MissingReasons.NoElementsFound));
143 |     }
144 | 
145 |     /// <summary>
146 |     /// Returns the last element of a sequence if such exists.
147 |     /// </summary>
148 |     /// <param name="source">The sequence to return the last element from.</param>
149 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
150 |     /// <returns>An <see cref="Option{TValue}"/> instance containing the last element if present.</returns>
151 |     public static Option<TSource> LastOrNone<TSource>(this IEnumerable<TSource> source, Error error = null)
152 |     {
153 |         ArgumentNullException.ThrowIfNull(source);
154 | 
155 |         if (source is IList<TSource> list)
156 |         {
157 |             var count = list.Count;
158 |             if (count > 0)
159 |             {
160 |                 return list[count - 1].Some();
161 |             }
162 |         }
163 |         else if (source is IReadOnlyList<TSource> readOnlyList)
164 |         {
165 |             var count = readOnlyList.Count;
166 |             if (count > 0)
167 |             {
168 |                 return readOnlyList[count - 1].Some();
169 |             }
170 |         }
171 |         else
172 |         {
173 |             using var enumerator = source.GetEnumerator();
174 |             if (enumerator.MoveNext())
175 |             {
176 |                 TSource result;
177 |                 do
178 |                 {
179 |                     result = enumerator.Current;
180 |                 }
181 |                 while (enumerator.MoveNext());
182 | 
183 |                 return result.Some();
184 |             }
185 |         }
186 | 
187 |         return Optional.None<TSource>(error ?? Error.Create(MissingReasons.CollectionWasEmpty));
188 |     }
189 | 
190 |     /// <summary>
191 |     /// Returns the last element of a sequence, satisfying a specified predicate,
192 |     /// if such exists.
193 |     /// </summary>
194 |     /// <param name="source">The sequence to return the last element from.</param>
195 |     /// <param name="predicate">The predicate to filter by.</param>
196 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
197 |     /// <returns>An <see cref="Option{TValue}"/> instance containing the last element if present.</returns>
198 |     public static Option<TSource> LastOrNone<TSource>(this IEnumerable<TSource> source, Predicate<TSource> predicate, Error error = null)
199 |     {
200 |         ArgumentNullException.ThrowIfNull(source);
201 | 
202 |         ArgumentNullException.ThrowIfNull(predicate);
203 | 
204 |         if (source is IList<TSource> list)
205 |         {
206 |             for (var i = list.Count - 1; i >= 0; --i)
207 |             {
208 |                 var result = list[i];
209 |                 if (predicate(result))
210 |                 {
211 |                     return result.Some();
212 |                 }
213 |             }
214 |         }
215 |         else if (source is IReadOnlyList<TSource> readOnlyList)
216 |         {
217 |             for (var i = readOnlyList.Count - 1; i >= 0; --i)
218 |             {
219 |                 var result = readOnlyList[i];
220 |                 if (predicate(result))
221 |                 {
222 |                     return result.Some();
223 |                 }
224 |             }
225 |         }
226 |         else
227 |         {
228 |             using var enumerator = source.GetEnumerator();
229 |             while (enumerator.MoveNext())
230 |             {
231 |                 var result = enumerator.Current;
232 |                 if (predicate(result))
233 |                 {
234 |                     while (enumerator.MoveNext())
235 |                     {
236 |                         var element = enumerator.Current;
237 |                         if (predicate(element))
238 |                         {
239 |                             result = element;
240 |                         }
241 |                     }
242 | 
243 |                     return result.Some();
244 |                 }
245 |             }
246 |         }
247 | 
248 |         return Optional.None<TSource>(error ?? Error.Create(MissingReasons.NoElementsFound));
249 |     }
250 | 
251 |     /// <summary>
252 |     /// Returns a single element from a sequence, if it exists
253 |     /// and is the only element in the sequence.
254 |     /// </summary>
255 |     /// <param name="source">The sequence to return the element from.</param>
256 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
257 |     /// <returns>An <see cref="Option{TValue}"/> instance containing the element if present.</returns>
258 |     public static Option<TSource> SingleOrNone<TSource>(this IEnumerable<TSource> source, Error error = null)
259 |     {
260 |         ArgumentNullException.ThrowIfNull(source);
261 | 
262 |         if (source is IList<TSource> list)
263 |         {
264 |             switch (list.Count)
265 |             {
266 |                 case 0: return Optional.None<TSource>(error ?? Error.Create(MissingReasons.CollectionWasEmpty));
267 |                 case 1: return list[0].Some();
268 |             }
269 |         }
270 |         else if (source is IReadOnlyList<TSource> readOnlyList)
271 |         {
272 |             switch (readOnlyList.Count)
273 |             {
274 |                 case 0: return Optional.None<TSource>(error ?? Error.Create(MissingReasons.CollectionWasEmpty));
275 |                 case 1: return readOnlyList[0].Some();
276 |             }
277 |         }
278 |         else
279 |         {
280 |             using var enumerator = source.GetEnumerator();
281 |             if (!enumerator.MoveNext())
282 |             {
283 |                 return Optional.None<TSource>(error ?? Error.Create(MissingReasons.CollectionWasEmpty));
284 |             }
285 | 
286 |             var result = enumerator.Current;
287 |             if (!enumerator.MoveNext())
288 |             {
289 |                 return result.Some();
290 |             }
291 |         }
292 | 
293 |         return Optional.None<TSource>(error ?? Error.Create(MissingReasons.CollectionWasEmpty));
294 |     }
295 | 
296 |     /// <summary>
297 |     /// Returns a single element from a sequence, satisfying a specified predicate,
298 |     /// if it exists and is the only element in the sequence.
299 |     /// </summary>
300 |     /// <param name="source">The sequence to return the element from.</param>
301 |     /// <param name="predicate">The predicate to filter by.</param>
302 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
303 |     /// <returns>An <see cref="Option{TValue}"/> instance containing the element if present.</returns>
304 |     public static Option<TSource> SingleOrNone<TSource>(this IEnumerable<TSource> source, Predicate<TSource> predicate, Error error = null)
305 |     {
306 |         ArgumentNullException.ThrowIfNull(source);
307 | 
308 |         ArgumentNullException.ThrowIfNull(predicate);
309 | 
310 |         using (var enumerator = source.GetEnumerator())
311 |         {
312 |             while (enumerator.MoveNext())
313 |             {
314 |                 var result = enumerator.Current;
315 |                 if (predicate(result))
316 |                 {
317 |                     while (enumerator.MoveNext())
318 |                     {
319 |                         if (predicate(enumerator.Current))
320 |                         {
321 |                             return Optional.None<TSource>(error ?? Error.Create(MissingReasons.NoElementsFound));
322 |                         }
323 |                     }
324 | 
325 |                     return result.Some();
326 |                 }
327 |             }
328 |         }
329 | 
330 |         return Optional.None<TSource>(error ?? Error.Create(MissingReasons.NoElementsFound));
331 |     }
332 | 
333 |     /// <summary>
334 |     /// Returns an element at a specified position in a sequence if such exists.
335 |     /// </summary>
336 |     /// <param name="source">The sequence to return the element from.</param>
337 |     /// <param name="index">The index in the sequence.</param>
338 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
339 |     /// <returns>An <see cref="Option{TValue}"/> instance containing the element if found.</returns>
340 |     public static Option<TSource> ElementAtOrNone<TSource>(this IEnumerable<TSource> source, int index, Error error = null)
341 |     {
342 |         ArgumentNullException.ThrowIfNull(source);
343 | 
344 |         if (index >= 0)
345 |         {
346 |             if (source is IList<TSource> list)
347 |             {
348 |                 if (index < list.Count)
349 |                 {
350 |                     return list[index].Some();
351 |                 }
352 |             }
353 |             else if (source is IReadOnlyList<TSource> readOnlyList)
354 |             {
355 |                 if (index < readOnlyList.Count)
356 |                 {
357 |                     return readOnlyList[index].Some();
358 |                 }
359 |             }
360 |             else
361 |             {
362 |                 using var enumerator = source.GetEnumerator();
363 |                 while (enumerator.MoveNext())
364 |                 {
365 |                     if (index == 0)
366 |                     {
367 |                         return enumerator.Current.Some();
368 |                     }
369 | 
370 |                     index--;
371 |                 }
372 |             }
373 |         }
374 | 
375 |         return Optional.None<TSource>(error ?? Error.Create(MissingReasons.IndexNotFound));
376 |     }
377 | 
378 |     /// <summary>
379 |     /// Aggregates a sequence of deferred options into one result, sequentially processing each option and short-circuiting the moment a result resolves into an unsuccessful outcome.
380 |     /// </summary>
381 |     /// <param name="lazyOptionsCollection">Sequence of <see cref="LazyOption"/>s to reduce.</param>
382 |     public static Option Reduce(this IEnumerable<LazyOption> lazyOptionsCollection)
383 |     {
384 |         return lazyOptionsCollection.Aggregate(Optional.Some(), (v1, v2) => v1.FlatMap(_ => v2.Resolve()));
385 |     }
386 | 
387 |     /// <summary>
388 |     /// Aggregates a sequence of asynchronously deferred options into one result, sequentially processing each option and short-circuiting the moment a result resolves into an unsuccessful outcome.
389 |     /// </summary>
390 |     /// <param name="lazyOptionsCollection">Sequence of <see cref="LazyOptionAsync"/> to reduce.</param>
391 |     public static async Task<Option> ReduceAsync(this IEnumerable<LazyOptionAsync> lazyOptionsCollection)
392 |     {
393 |         return await AggregateAsync(lazyOptionsCollection, Optional.Some(), async (v1, v2) => await v1.FlatMapAsync(_ => v2.Resolve()));
394 | 
395 |         static async Task<TAccumulate> AggregateAsync<TSource, TAccumulate>(IEnumerable<TSource> source, TAccumulate result, Func<TAccumulate, TSource, Task<TAccumulate>> func)
396 |         {
397 |             using var enumerator = source.GetEnumerator();
398 |             if (!enumerator.MoveNext())
399 |             {
400 |                 throw new InvalidOperationException("Sequence contains no elements");
401 |             }
402 | 
403 |             do
404 |             {
405 |                 result = await func(result, enumerator.Current);
406 |             } while (enumerator.MoveNext());
407 | 
408 |             return result;
409 |         }
410 |     }
411 | 
412 | 
413 |     /// <summary>
414 |     /// Transforms each item in a sequence according to the specified option-returning transformation function, short-circuiting the moment a function iteration results in an empty optional.
415 |     /// </summary>
416 |     /// <typeparam name="TSource">The type of the source item to transform.</typeparam>
417 |     /// <typeparam name="TResult">The type of the resulting optional value.</typeparam>
418 |     /// <param name="source">Sequence of items to transform.</param>
419 |     /// <param name="func">Transformation function to apply to each item of the sequence.</param>
420 |     public static Option<IReadOnlyList<TResult>> Transform<TSource, TResult>(this IEnumerable<TSource> source, Func<TSource, Option<TResult>> func)
421 |     {
422 |         Option<TResult>? failedTransformation = null;
423 | 
424 |         var transformationResult = TransformLocal().ToList();
425 | 
426 |         if (failedTransformation.HasValue)
427 |         {
428 |             return Optional.None<IReadOnlyList<TResult>>(failedTransformation.Value.Error);
429 |         }
430 | 
431 |         return Optional.Some<IReadOnlyList<TResult>>(transformationResult.AsReadOnly());
432 | 
433 |         IEnumerable<TResult> TransformLocal()
434 |         {
435 |             foreach (var item in source)
436 |             {
437 |                 var result = func(item);
438 | 
439 |                 if (result.HasValue)
440 |                 {
441 |                     yield return result.Value;
442 |                 }
443 |                 else
444 |                 {
445 |                     failedTransformation = result;
446 | 
447 |                     yield break;
448 |                 }
449 |             }
450 |         }
451 |     }
452 | }
453 | 


--------------------------------------------------------------------------------
/src/Utilities/TryParse.cs:
--------------------------------------------------------------------------------
  1 | namespace Ultimately.Utilities;
  2 | 
  3 | using Reasons;
  4 | 
  5 | using System;
  6 | using System.Globalization;
  7 | 
  8 | 
  9 | /// <summary>
 10 | /// A collection of static helper methods for parsing strings into simple types.
 11 | /// </summary>
 12 | public static class TryParse
 13 | {
 14 |     private delegate bool ParsingFunction<TValue>(string s, out TValue result);
 15 | 
 16 |     private delegate bool ParsingFunctionWithFormat<TValue>(string s, NumberStyles style, IFormatProvider provider, out TValue result);
 17 | 
 18 |     private delegate bool DateParsingFunctionWithFormat1<TValue>(string s, IFormatProvider provider, DateTimeStyles styles, out TValue result);
 19 | 
 20 |     private delegate bool DateParsingFunctionWithFormat2<TValue>(string s, string format, IFormatProvider provider, DateTimeStyles style, out TValue result);
 21 | 
 22 |     private delegate bool DateParsingFunctionWithFormat3<TValue>(string s, string[] formats, IFormatProvider provider, DateTimeStyles style, out TValue result);
 23 | 
 24 |     private static Option<TValue> To<TValue>(string s, ParsingFunction<TValue> parsingFunction, Error error = null)
 25 |     {
 26 |         return parsingFunction(s, out var result) ? result.Some() : Optional.None<TValue>(error ?? MissingReasons.CouldNotBeParsedAs<TValue>.Value);
 27 |     }
 28 | 
 29 |     private static Option<TValue> To<TValue>(string s, NumberStyles style, IFormatProvider provider, ParsingFunctionWithFormat<TValue> parsingFunctionWithFormat, Error error = null)
 30 |     {
 31 |         return parsingFunctionWithFormat(s, style, provider, out var result) ? result.Some() : Optional.None<TValue>(error ?? MissingReasons.CouldNotBeParsedAs<TValue>.Value);
 32 |     }
 33 | 
 34 |     private static Option<TValue> To<TValue>(string s, IFormatProvider provider, DateTimeStyles styles, DateParsingFunctionWithFormat1<TValue> parsingFunctionWithFormat, Error error = null)
 35 |     {
 36 |         return parsingFunctionWithFormat(s, provider, styles, out var result) ? result.Some() : Optional.None<TValue>(error ?? MissingReasons.CouldNotBeParsedAs<TValue>.Value);
 37 |     }
 38 | 
 39 |     private static Option<TValue> To<TValue>(string s, string format, IFormatProvider provider, DateTimeStyles style,  DateParsingFunctionWithFormat2<TValue> parsingFunctionWithFormat, Error error = null)
 40 |     {
 41 |         return parsingFunctionWithFormat(s, format, provider, style, out var result) ? result.Some() : Optional.None<TValue>(error ?? MissingReasons.CouldNotBeParsedAs<TValue>.Value);
 42 |     }
 43 | 
 44 |     private static Option<TValue> To<TValue>(string s, string[] formats, IFormatProvider provider, DateTimeStyles style, DateParsingFunctionWithFormat3<TValue> parsingFunctionWithFormat, Error error = null)
 45 |     {
 46 |         return parsingFunctionWithFormat(s, formats, provider, style, out var result) ? result.Some() : Optional.None<TValue>(error ?? MissingReasons.CouldNotBeParsedAs<TValue>.Value);
 47 |     }
 48 | 
 49 |     /// <summary>
 50 |     /// Tries to parse a string into a byte.
 51 |     /// </summary>
 52 |     /// <returns>An optional value containing the result if any.</returns>
 53 |     public static Option<byte> ToByte(string s, Error error = null)
 54 |     {
 55 |         return To<byte>(s, byte.TryParse, error);
 56 |     }
 57 | 
 58 |     /// <summary>
 59 |     /// Tries to parse a string into a byte.
 60 |     /// </summary>
 61 |     /// <returns>An optional value containing the result if any.</returns>
 62 |     public static Option<byte> ToByte(string s, NumberStyles style, IFormatProvider provider, Error error = null)
 63 |     {
 64 |         return To<byte>(s, style, provider, byte.TryParse, error);
 65 |     }
 66 | 
 67 |     /// <summary>
 68 |     /// Tries to parse a string into a signed byte.
 69 |     /// </summary>
 70 |     /// <returns>An optional value containing the result if any.</returns>
 71 |     public static Option<sbyte> ToSByte(string s, Error error = null)
 72 |     {
 73 |         return To<sbyte>(s, sbyte.TryParse, error);
 74 |     }
 75 | 
 76 |     /// <summary>
 77 |     /// Tries to parse a string into a signed byte.
 78 |     /// </summary>
 79 |     /// <returns>An optional value containing the result if any.</returns>
 80 |     public static Option<sbyte> ToSByte(string s, NumberStyles style, IFormatProvider provider, Error error = null)
 81 |     {
 82 |         return To<sbyte>(s, style, provider, sbyte.TryParse, error);
 83 |     }
 84 | 
 85 |     /// <summary>
 86 |     /// Tries to parse a string into a short.
 87 |     /// </summary>
 88 |     /// <returns>An optional value containing the result if any.</returns>
 89 |     public static Option<short> ToShort(string s, Error error = null)
 90 |     {
 91 |         return To<short>(s, short.TryParse, error);
 92 |     }
 93 | 
 94 |     /// <summary>
 95 |     /// Tries to parse a string into a short.
 96 |     /// </summary>
 97 |     /// <returns>An optional value containing the result if any.</returns>
 98 |     public static Option<short> ToShort(string s, NumberStyles style, IFormatProvider provider, Error error = null)
 99 |     {
100 |         return To<short>(s, style, provider, short.TryParse, error);
101 |     }
102 | 
103 |     /// <summary>
104 |     /// Tries to parse a string into an unsigned short.
105 |     /// </summary>
106 |     /// <returns>An optional value containing the result if any.</returns>
107 |     public static Option<ushort> ToUShort(string s, Error error = null)
108 |     {
109 |         return To<ushort>(s, ushort.TryParse, error);
110 |     }
111 | 
112 |     /// <summary>
113 |     /// Tries to parse a string into an unsigned short.
114 |     /// </summary>
115 |     /// <returns>An optional value containing the result if any.</returns>
116 |     public static Option<ushort> ToUShort(string s, NumberStyles style, IFormatProvider provider, Error error = null)
117 |     {
118 |         return To<ushort>(s, style, provider, ushort.TryParse, error);
119 |     }
120 | 
121 |     /// <summary>
122 |     /// Tries to parse a string into an int.
123 |     /// </summary>
124 |     /// <returns>An optional value containing the result if any.</returns>
125 |     public static Option<int> ToInt(string s, Error error = null)
126 |     {
127 |         return To<int>(s, int.TryParse, error);
128 |     }
129 | 
130 |     /// <summary>
131 |     /// Tries to parse a string into an int.
132 |     /// </summary>
133 |     /// <returns>An optional value containing the result if any.</returns>
134 |     public static Option<int> ToInt(string s, NumberStyles style, IFormatProvider provider, Error error = null)
135 |     {
136 |         return To<int>(s, style, provider, int.TryParse, error);
137 |     }
138 | 
139 |     /// <summary>
140 |     /// Tries to parse a string into an unsigned int.
141 |     /// </summary>
142 |     /// <returns>An optional value containing the result if any.</returns>
143 |     public static Option<uint> ToUInt(string s, Error error = null)
144 |     {
145 |         return To<uint>(s, uint.TryParse, error);
146 |     }
147 | 
148 |     /// <summary>
149 |     /// Tries to parse a string into an unsigned int.
150 |     /// </summary>
151 |     /// <returns>An optional value containing the result if any.</returns>
152 |     public static Option<uint> ToUInt(string s, NumberStyles style, IFormatProvider provider, Error error = null)
153 |     {
154 |         return To<uint>(s, style, provider, uint.TryParse, error);
155 |     }
156 | 
157 |     /// <summary>
158 |     /// Tries to parse a string into a long.
159 |     /// </summary>
160 |     /// <returns>An optional value containing the result if any.</returns>
161 |     public static Option<long> ToLong(string s, Error error = null)
162 |     {
163 |         return To<long>(s, long.TryParse, error);
164 |     }
165 | 
166 |     /// <summary>
167 |     /// Tries to parse a string into a long.
168 |     /// </summary>
169 |     /// <returns>An optional value containing the result if any.</returns>
170 |     public static Option<long> ToLong(string s, NumberStyles style, IFormatProvider provider, Error error = null)
171 |     {
172 |         return To<long>(s, style, provider, long.TryParse, error);
173 |     }
174 | 
175 |     /// <summary>
176 |     /// Tries to parse a string into an unsigned long.
177 |     /// </summary>
178 |     /// <returns>An optional value containing the result if any.</returns>
179 |     public static Option<ulong> ToULong(string s, Error error = null)
180 |     {
181 |         return To<ulong>(s, ulong.TryParse, error);
182 |     }
183 | 
184 |     /// <summary>
185 |     /// Tries to parse a string into an unsigned long.
186 |     /// </summary>
187 |     /// <returns>An optional value containing the result if any.</returns>
188 |     public static Option<ulong> ToULong(string s, NumberStyles style, IFormatProvider provider, Error error = null)
189 |     {
190 |         return To<ulong>(s, style, provider, ulong.TryParse, error);
191 |     }
192 | 
193 |     /// <summary>
194 |     /// Tries to parse a string into a float.
195 |     /// </summary>
196 |     /// <returns>An optional value containing the result if any.</returns>
197 |     public static Option<float> ToFloat(string s, Error error = null)
198 |     {
199 |         return To<float>(s, float.TryParse, error);
200 |     }
201 | 
202 |     /// <summary>
203 |     /// Tries to parse a string into a float.
204 |     /// </summary>
205 |     /// <returns>An optional value containing the result if any.</returns>
206 |     public static Option<float> ToFloat(string s, NumberStyles style, IFormatProvider provider, Error error = null)
207 |     {
208 |         return To<float>(s, style, provider, float.TryParse, error);
209 |     }
210 | 
211 |     /// <summary>
212 |     /// Tries to parse a string into a double.
213 |     /// </summary>
214 |     /// <returns>An optional value containing the result if any.</returns>
215 |     public static Option<double> ToDouble(string s, Error error = null)
216 |     {
217 |         return To<double>(s, double.TryParse, error);
218 |     }
219 | 
220 |     /// <summary>
221 |     /// Tries to parse a string into a double.
222 |     /// </summary>
223 |     /// <returns>An optional value containing the result if any.</returns>
224 |     public static Option<double> ToDouble(string s, NumberStyles style, IFormatProvider provider, Error error = null)
225 |     {
226 |         return To<double>(s, style, provider, double.TryParse, error);
227 |     }
228 | 
229 |     /// <summary>
230 |     /// Tries to parse a string into a decimal.
231 |     /// </summary>
232 |     /// <returns>An optional value containing the result if any.</returns>
233 |     public static Option<decimal> ToDecimal(string s, Error error = null)
234 |     {
235 |         return To<decimal>(s, decimal.TryParse, error);
236 |     }
237 | 
238 |     /// <summary>
239 |     /// Tries to parse a string into a decimal.
240 |     /// </summary>
241 |     /// <returns>An optional value containing the result if any.</returns>
242 |     public static Option<decimal> ToDecimal(string s, NumberStyles style, IFormatProvider provider, Error error = null)
243 |     {
244 |         return To<decimal>(s, style, provider, decimal.TryParse, error);
245 |     }
246 | 
247 |     /// <summary>
248 |     /// Tries to parse a string into a bool.
249 |     /// </summary>
250 |     /// <returns>An optional value containing the result if any.</returns>
251 |     public static Option<bool> ToBool(string s, Error error = null)
252 |     {
253 |         return To<bool>(s, bool.TryParse, error);
254 |     }
255 | 
256 |     /// <summary>
257 |     /// Tries to parse a string into a char.
258 |     /// </summary>
259 |     /// <returns>An optional value containing the result if any.</returns>
260 |     public static Option<char> ToChar(string s, Error error = null)
261 |     {
262 |         return To<char>(s, char.TryParse, error);
263 |     }
264 | 
265 | 
266 |     /// <summary>
267 |     /// Tries to parse a string into a guid.
268 |     /// </summary>
269 |     /// <returns>An optional value containing the result if any.</returns>
270 |     public static Option<Guid> ToGuid(string s, Error error = null)
271 |     {
272 |         return To<Guid>(s, Guid.TryParse, error);
273 |     }
274 | 
275 |     /// <summary>
276 |     /// Tries to parse a string into an enum.
277 |     /// </summary>
278 |     /// <returns>An optional value containing the result if any.</returns>
279 |     public static Option<TEnum> ToEnum<TEnum>(string s, Error error = null)
280 |         where TEnum : struct, Enum
281 |     {
282 |         return To<TEnum>(s, Enum.TryParse, error);
283 |     }
284 | 
285 |     /// <summary>
286 |     /// Tries to parse a string into an enum.
287 |     /// </summary>
288 |     /// <returns>An optional value containing the result if any.</returns>
289 |     public static Option<TEnum> ToEnum<TEnum>(string s, bool ignoreCase, Error error = null)
290 |         where TEnum : struct, Enum
291 |     {
292 |         return Enum.TryParse<TEnum>(s, ignoreCase, out var result) ? result.Some() : Optional.None<TEnum>(error ?? MissingReasons.CouldNotBeParsedAs<TEnum>.Value);
293 |     }
294 | 
295 |     /// <summary>
296 |     /// Tries to parse a string into a datetime.
297 |     /// </summary>
298 |     /// <returns>An optional value containing the result if any.</returns>
299 |     public static Option<DateTime> ToDateTime(string s, Error error = null)
300 |     {
301 |         return To<DateTime>(s, DateTime.TryParse, error);
302 |     }
303 | 
304 |     /// <summary>
305 |     /// Tries to parse a string into a datetime.
306 |     /// </summary>
307 |     /// <returns>An optional value containing the result if any.</returns>
308 |     public static Option<DateTime> ToDateTime(string s, IFormatProvider provider, DateTimeStyles styles, Error error = null)
309 |     {
310 |         return To<DateTime>(s, provider, styles, DateTime.TryParse, error);
311 |     }
312 | 
313 |     /// <summary>
314 |     /// Tries to parse a string into a datetime with a specific format.
315 |     /// </summary>
316 |     /// <returns>An optional value containing the result if any.</returns>
317 |     public static Option<DateTime> ToDateTimeExact(string s, string format, IFormatProvider provider, DateTimeStyles styles, Error error = null)
318 |     {
319 |         return To<DateTime>(s, format, provider, styles, DateTime.TryParseExact, error);
320 |     }
321 | 
322 |     /// <summary>
323 |     /// Tries to parse a string into a datetime with a specific format.
324 |     /// </summary>
325 |     /// <returns>An optional value containing the result if any.</returns>
326 |     public static Option<DateTime> ToDateTimeExact(string s, string[] formats, IFormatProvider provider, DateTimeStyles styles, Error error = null)
327 |     {
328 |         return To<DateTime>(s, formats, provider, styles, DateTime.TryParseExact, error);
329 |     }
330 | 
331 |     /// <summary>
332 |     /// Tries to parse a string into a timespan.
333 |     /// </summary>
334 |     /// <returns>An optional value containing the result if any.</returns>
335 |     public static Option<TimeSpan> ToTimeSpan(string s, Error error = null)
336 |     {
337 |         return To<TimeSpan>(s, TimeSpan.TryParse, error);
338 |     }
339 | 
340 |     /// <summary>
341 |     /// Tries to parse a string into a timespan.
342 |     /// </summary>
343 |     /// <returns>An optional value containing the result if any.</returns>
344 |     public static Option<TimeSpan> ToTimeSpan(string s, IFormatProvider provider, Error error = null)
345 |     {
346 |         return TimeSpan.TryParse(s, provider, out var result) ? result.Some() : Optional.None<TimeSpan>(error ?? MissingReasons.CouldNotBeParsedAs<TimeSpan>.Value);
347 |     }
348 | 
349 |     /// <summary>
350 |     /// Tries to parse a string into a timespan with a specific format.
351 |     /// </summary>
352 |     /// <returns>An optional value containing the result if any.</returns>
353 |     public static Option<TimeSpan> ToTimeSpanExact(string s, string format, IFormatProvider provider, Error error = null)
354 |     {
355 |         return TimeSpan.TryParseExact(s, format, provider, out var result) ? result.Some() : Optional.None<TimeSpan>(error ?? MissingReasons.CouldNotBeParsedAs<TimeSpan>.Value);
356 |     }
357 | 
358 |     /// <summary>
359 |     /// Tries to parse a string into a timespan with a specific format.
360 |     /// </summary>
361 |     /// <returns>An optional value containing the result if any.</returns>
362 |     public static Option<TimeSpan> ToTimeSpanExact(string s, string[] formats, IFormatProvider provider, Error error = null)
363 |     {
364 |         return TimeSpan.TryParseExact(s, formats, provider, out var result) ? result.Some() : Optional.None<TimeSpan>(error ?? MissingReasons.CouldNotBeParsedAs<TimeSpan>.Value);
365 |     }
366 | 
367 |     /// <summary>
368 |     /// Tries to parse a string into a timespan with a specific format.
369 |     /// </summary>
370 |     /// <returns>An optional value containing the result if any.</returns>
371 |     public static Option<TimeSpan> ToTimeSpanExact(string s, string format, IFormatProvider provider, TimeSpanStyles styles, Error error = null)
372 |     {
373 |         return TimeSpan.TryParseExact(s, format, provider, styles, out var result) ? result.Some() : Optional.None<TimeSpan>(error ?? MissingReasons.CouldNotBeParsedAs<TimeSpan>.Value);
374 |     }
375 | 
376 |     /// <summary>
377 |     /// Tries to parse a string into a timespan with a specific format.
378 |     /// </summary>
379 |     /// <returns>An optional value containing the result if any.</returns>
380 |     public static Option<TimeSpan> ToTimeSpanExact(string s, string[] formats, IFormatProvider provider, TimeSpanStyles styles, Error error = null)
381 |     {
382 |         return TimeSpan.TryParseExact(s, formats, provider, styles, out var result) ? result.Some() : Optional.None<TimeSpan>(error ?? MissingReasons.CouldNotBeParsedAs<TimeSpan>.Value);
383 |     }
384 | 
385 |     /// <summary>
386 |     /// Tries to parse a string into a datetime offset.
387 |     /// </summary>
388 |     /// <returns>An optional value containing the result if any.</returns>
389 |     public static Option<DateTimeOffset> ToDateTimeOffset(string s, Error error = null)
390 |     {
391 |         return To<DateTimeOffset>(s, DateTimeOffset.TryParse, error);
392 |     }
393 | 
394 |     /// <summary>
395 |     /// Tries to parse a string into a datetime offset.
396 |     /// </summary>
397 |     /// <returns>An optional value containing the result if any.</returns>
398 |     public static Option<DateTimeOffset> ToDateTimeOffset(string s, IFormatProvider provider, DateTimeStyles styles, Error error = null)
399 |     {
400 |         return To<DateTimeOffset>(s, provider, styles, DateTimeOffset.TryParse, error);
401 |     }
402 | 
403 |     /// <summary>
404 |     /// Tries to parse a string into a datetime offset with a specific format.
405 |     /// </summary>
406 |     /// <returns>An optional value containing the result if any.</returns>
407 |     public static Option<DateTimeOffset> ToDateTimeOffsetExact(string s, string format, IFormatProvider provider, DateTimeStyles styles, Error error = null)
408 |     {
409 |         return To<DateTimeOffset>(s, format, provider, styles, DateTimeOffset.TryParseExact, error);
410 |     }
411 | 
412 |     /// <summary>
413 |     /// Tries to parse a string into a datetime offset with a specific format.
414 |     /// </summary>
415 |     /// <returns>An optional value containing the result if any.</returns>
416 |     public static Option<DateTimeOffset> ToDateTimeOffsetExact(string s, string[] formats, IFormatProvider provider, DateTimeStyles styles, Error error = null)
417 |     {
418 |         return To<DateTimeOffset>(s, formats, provider, styles, DateTimeOffset.TryParseExact, error);
419 |     }
420 | }
421 | 


--------------------------------------------------------------------------------
/src/Option_Either.cs:
--------------------------------------------------------------------------------
  1 | namespace Ultimately;
  2 | 
  3 | using Reasons;
  4 | 
  5 | using System;
  6 | using System.Collections;
  7 | using System.Collections.Generic;
  8 | using System.Linq;
  9 | 
 10 | /// <summary>
 11 | /// Wraps an optional value that may or may not exist depending on a predetermined set of business rules.
 12 | /// </summary>
 13 | /// <typeparam name="TValue">The type of the value to be wrapped.</typeparam>
 14 | [Serializable]
 15 | public readonly struct Option<TValue>
 16 | {
 17 |     /// <summary>
 18 |     /// Indicates whether or not the optional contains a value.
 19 |     /// </summary>
 20 |     public bool HasValue { get; }
 21 | 
 22 |     internal TValue Value { get; }
 23 | 
 24 |     internal Success Success { get; }
 25 | 
 26 |     internal Error Error { get; }
 27 | 
 28 |     internal Option(bool hasValue, TValue value, Success success, Error error)
 29 |     {
 30 |         HasValue = hasValue;
 31 |         Value = value;
 32 |         Success = success;
 33 |         Error = error;
 34 |     }
 35 | 
 36 |     /// <summary>
 37 |     /// Converts the current optional into an enumerable with one or zero elements.
 38 |     /// </summary>
 39 |     /// <returns>A corresponding enumerable.</returns>
 40 |     public IEnumerable<TValue> ToEnumerable()
 41 |     {
 42 |         if (HasValue)
 43 |         {
 44 |             yield return Value;
 45 |         }
 46 |     }
 47 | 
 48 |     /// <summary>
 49 |     /// Returns an enumerator for the optional.
 50 |     /// </summary>
 51 |     /// <returns>The enumerator.</returns>
 52 |     public IEnumerator<(TValue Value, Success Success)> GetEnumerator()
 53 |     {
 54 |         if (HasValue)
 55 |         {
 56 |             yield return (Value, Success);
 57 |         }
 58 |     }
 59 | 
 60 |     /// <summary>
 61 |     /// Determines if the current optional contains a specified value.
 62 |     /// </summary>
 63 |     /// <param name="value">The value to locate.</param>
 64 |     /// <returns>A boolean indicating whether or not the value was found.</returns>
 65 |     public bool Contains(TValue value)
 66 |     {
 67 |         if (HasValue)
 68 |         {
 69 |             if (Value == null)
 70 |             {
 71 |                 return value == null;
 72 |             }
 73 | 
 74 |             return Value.Equals(value);
 75 |         }
 76 | 
 77 |         return false;
 78 |     }
 79 | 
 80 |     /// <summary>
 81 |     /// Determines if the current optional contains a value satisfying a specified predicate.
 82 |     /// </summary>
 83 |     /// <param name="predicate">A predicate to test the optional value against.</param>
 84 |     /// <returns>A boolean indicating whether or not the predicate was satisfied.</returns>
 85 |     public bool Exists(Predicate<TValue> predicate)
 86 |     {
 87 |         ArgumentNullException.ThrowIfNull(predicate);
 88 | 
 89 |         return HasValue && predicate(Value);
 90 |     }
 91 | 
 92 |     /// <summary>
 93 |     /// Returns the existing value if present, or otherwise an alternative value.
 94 |     /// </summary>
 95 |     /// <param name="alternative">The alternative value.</param>
 96 |     /// <returns>The existing or alternative value.</returns>
 97 |     public TValue ValueOr(TValue alternative) => HasValue ? Value : alternative;
 98 | 
 99 |     /// <summary>
100 |     /// Returns the existing value if present, or otherwise an alternative value.
101 |     /// </summary>
102 |     /// <param name="alternativeFactory">A factory function to create an alternative value.</param>
103 |     /// <returns>The existing or alternative value.</returns>
104 |     public TValue ValueOr(Func<TValue> alternativeFactory)
105 |     {
106 |         ArgumentNullException.ThrowIfNull(alternativeFactory);
107 | 
108 |         return HasValue ? Value : alternativeFactory();
109 |     }
110 | 
111 |     /// <summary>
112 |     /// Uses an alternative value if no existing value is present.
113 |     /// </summary>
114 |     /// <param name="alternative">The alternative value.</param>
115 |     /// <returns>A new optional, containing either the existing or alternative value.</returns>
116 |     public Option<TValue> Or(TValue alternative) => HasValue ? this : Optional.Some(alternative);
117 | 
118 |     /// <summary>
119 |     /// Uses an alternative value if no existing value is present and attaches the specified success object.
120 |     /// </summary>
121 |     /// <param name="alternative">The alternative value.</param>
122 |     /// <param name="success">An object with data describing the reason or origin behind the presence of the alternative optional value.</param>
123 |     /// <returns>A new optional, containing either the existing or alternative value.</returns>
124 |     public Option<TValue> Or(TValue alternative, Success success) => HasValue ? this : Optional.Some(alternative, success);
125 | 
126 |     /// <summary>
127 |     /// Uses an alternative value if no existing value is present.
128 |     /// </summary>
129 |     /// <param name="alternativeFactory">A factory function to create an alternative value.</param>
130 |     /// <returns>A new optional, containing either the existing or alternative value.</returns>
131 |     public Option<TValue> Or(Func<TValue> alternativeFactory)
132 |     {
133 |         ArgumentNullException.ThrowIfNull(alternativeFactory);
134 | 
135 |         return HasValue ? this : Optional.Some(alternativeFactory());
136 |     }
137 | 
138 |     /// <summary>
139 |     /// Uses an alternative value if no existing value is present and attaches the specified success object.
140 |     /// </summary>
141 |     /// <param name="alternativeFactory">A factory function to create an alternative value.</param>
142 |     /// <param name="success">An object with data describing the reason or origin behind the presence of the alternative optional value.</param>
143 |     /// <returns>A new optional, containing either the existing or alternative value.</returns>
144 |     public Option<TValue> Or(Func<TValue> alternativeFactory, Success success)
145 |     {
146 |         ArgumentNullException.ThrowIfNull(alternativeFactory);
147 | 
148 |         return HasValue ? this : Optional.Some(alternativeFactory(), success);
149 |     }
150 | 
151 |     /// <summary>
152 |     /// Uses an alternative optional, if no existing value is present.
153 |     /// </summary>
154 |     /// <param name="alternativeOption">The alternative optional.</param>
155 |     /// <returns>The alternative optional, if no value is present, otherwise itself.</returns>
156 |     public Option<TValue> Else(Option<TValue> alternativeOption) => HasValue ? this : alternativeOption;
157 | 
158 |     /// <summary>
159 |     /// Uses an alternative optional, if no existing value is present.
160 |     /// </summary>
161 |     /// <param name="alternativeOptionFactory">A factory function to create an alternative optional.</param>
162 |     /// <returns>The alternative optional, if no value is present, otherwise itself.</returns>
163 |     public Option<TValue> Else(Func<Option<TValue>> alternativeOptionFactory)
164 |     {
165 |         ArgumentNullException.ThrowIfNull(alternativeOptionFactory);
166 | 
167 |         return HasValue ? this : alternativeOptionFactory();
168 |     }
169 | 
170 |     /// <summary>
171 |     /// Evaluates a specified function, based on whether a value is present or not.
172 |     /// </summary>
173 |     /// <param name="some">The function to evaluate if the value is present.</param>
174 |     /// <param name="none">The function to evaluate if the value is missing.</param>
175 |     /// <returns>The result of the evaluated function.</returns>
176 |     public TResult Match<TResult>(Func<TValue, TResult> some, Func<Error, TResult> none)
177 |     {
178 |         ArgumentNullException.ThrowIfNull(some);
179 |         ArgumentNullException.ThrowIfNull(none);
180 | 
181 |         return HasValue ? some(Value) : none(Error);
182 |     }
183 | 
184 |     /// <summary>
185 |     /// Evaluates a specified function, based on whether a value is present or not.
186 |     /// </summary>
187 |     /// <param name="some">The function to evaluate if the value is present.</param>
188 |     /// <param name="none">The function to evaluate if the value is missing.</param>
189 |     /// <returns>The result of the evaluated function.</returns>
190 |     public TResult Match<TResult>(Func<TValue, Success, TResult> some, Func<Error, TResult> none)
191 |     {
192 |         ArgumentNullException.ThrowIfNull(some);
193 |         ArgumentNullException.ThrowIfNull(none);
194 | 
195 |         return HasValue ? some(Value, Success) : none(Error);
196 |     }
197 | 
198 |     /// <summary>
199 |     /// Evaluates a specified action, based on whether a value is present or not.
200 |     /// </summary>
201 |     /// <param name="some">The action to evaluate if the value is present.</param>
202 |     /// <param name="none">The action to evaluate if the value is missing.</param>
203 |     public void Match(Action<TValue> some, Action<Error> none)
204 |     {
205 |         ArgumentNullException.ThrowIfNull(some);
206 |         ArgumentNullException.ThrowIfNull(none);
207 | 
208 |         if (HasValue)
209 |         {
210 |             some(Value);
211 |         }
212 |         else
213 |         {
214 |             none(Error);
215 |         }
216 |     }
217 | 
218 |     /// <summary>
219 |     /// Evaluates a specified action, based on whether a value is present or not.
220 |     /// </summary>
221 |     /// <param name="some">The action to evaluate if the value is present.</param>
222 |     /// <param name="none">The action to evaluate if the value is missing.</param>
223 |     public void Match(Action<TValue, Success> some, Action<Error> none)
224 |     {
225 |         ArgumentNullException.ThrowIfNull(some);
226 |         ArgumentNullException.ThrowIfNull(none);
227 | 
228 |         if (HasValue)
229 |         {
230 |             some(Value, Success);
231 |         }
232 |         else
233 |         {
234 |             none(Error);
235 |         }
236 |     }
237 | 
238 |     /// <summary>
239 |     /// Evaluates a specified action if a value is present.
240 |     /// </summary>
241 |     /// <param name="some">The action to evaluate if the value is present.</param>
242 |     public void MatchSome(Action<TValue> some)
243 |     {
244 |         ArgumentNullException.ThrowIfNull(some);
245 | 
246 |         if (HasValue)
247 |         {
248 |             some(Value);
249 |         }
250 |     }
251 | 
252 |     /// <summary>
253 |     /// Evaluates a specified action if a value is present.
254 |     /// </summary>
255 |     /// <param name="some">The action to evaluate if the value is present.</param>
256 |     public void MatchSome(Action<TValue, Success> some)
257 |     {
258 |         ArgumentNullException.ThrowIfNull(some);
259 | 
260 |         if (HasValue)
261 |         {
262 |             some(Value, Success);
263 |         }
264 |     }
265 | 
266 |     /// <summary>
267 |     /// Evaluates a specified action if no value is present.
268 |     /// </summary>
269 |     /// <param name="none">The action to evaluate if the value is missing.</param>
270 |     public void MatchNone(Action<Error> none)
271 |     {
272 |         ArgumentNullException.ThrowIfNull(none);
273 | 
274 |         if (!HasValue)
275 |         {
276 |             none(Error);
277 |         }
278 |     }
279 | 
280 |     /// <summary>
281 |     /// Transforms the inner value of an optional. If the instance is empty, an empty optional is returned.
282 |     /// </summary>
283 |     /// <param name="mapping">The transformation function.</param>
284 |     /// <param name="subsequentError">If the resulting optional is empty, sets its error as the direct reason to the specified subsequent error.</param>
285 |     /// <returns>The transformed optional.</returns>
286 |     public Option<TResult> Map<TResult>(Func<TValue, TResult> mapping, Error subsequentError = null)
287 |     {
288 |         ArgumentNullException.ThrowIfNull(mapping);
289 | 
290 |         Func<Error, Option<TResult>> errorFunc = Optional.None<TResult>;
291 | 
292 |         if (subsequentError != null)
293 |         {
294 |             errorFunc = e => Optional.None<TResult>(subsequentError.CausedBy(e));
295 |         }
296 | 
297 |         return Match(
298 |                      some: v => Optional.Some(mapping(v)),
299 |                      none: errorFunc
300 |                     );
301 |     }
302 | 
303 |     /// <summary>
304 |     /// Transforms the inner value of an optional. If the instance is empty, an empty optional is returned.
305 |     /// </summary>
306 |     /// <param name="mapping">The transformation function.</param>
307 |     /// <param name="subsequentError">If the resulting optional is empty, sets its error as the direct reason to the specified subsequent error.</param>
308 |     /// <returns>The transformed optional.</returns>
309 |     public Option<TResult> Map<TResult>(Func<TValue, Success, TResult> mapping, Error subsequentError = null)
310 |     {
311 |         ArgumentNullException.ThrowIfNull(mapping);
312 | 
313 |         Func<Error, Option<TResult>> errorFunc = Optional.None<TResult>;
314 | 
315 |         if (subsequentError != null)
316 |         {
317 |             errorFunc = e => Optional.None<TResult>(subsequentError.CausedBy(e));
318 |         }
319 | 
320 |         return Match(
321 |                      some: (v, s) => Optional.Some(mapping(v, s)),
322 |                      none: errorFunc
323 |                     );
324 |     }
325 | 
326 |     /// <summary>
327 |     /// Transforms the inner value of an optional into another optional. The result is flattened, and if either is empty, an empty optional is returned.
328 |     /// </summary>
329 |     /// <param name="mapping">The transformation function.</param>
330 |     /// <param name="subsequentError">If the resulting optional is empty, sets its error as the direct reason to the specified subsequent error.</param>
331 |     /// <returns>The transformed optional.</returns>
332 |     public Option<TResult> FlatMap<TResult>(Func<TValue, Option<TResult>> mapping, Error subsequentError = null)
333 |     {
334 |         ArgumentNullException.ThrowIfNull(mapping);
335 | 
336 |         Option<TResult> result;
337 | 
338 |         if (HasValue)
339 |         {
340 |             result = mapping(Value);
341 | 
342 |             result.MatchNone(e =>
343 |             {
344 |                 if (subsequentError != null)
345 |                 {
346 |                     result = Optional.None<TResult>(subsequentError.CausedBy(e));
347 |                 }
348 |             });
349 |         }
350 |         else
351 |         {
352 |             result = Optional.None<TResult>(subsequentError != null ? subsequentError.CausedBy(Error) : Error);
353 |         }
354 | 
355 |         return result;
356 |     }
357 | 
358 |     /// <summary>
359 |     /// Transforms the inner value of an optional into another optional. The result is flattened, and if either is empty, an empty optional is returned.
360 |     /// </summary>
361 |     /// <param name="mapping">The transformation function.</param>
362 |     /// <param name="subsequentError">If the resulting optional is empty, sets its error as the direct reason to the specified subsequent error.</param>
363 |     /// <returns>The transformed optional.</returns>
364 |     public Option<TResult> FlatMap<TResult>(Func<TValue, Success, Option<TResult>> mapping, Error subsequentError = null)
365 |     {
366 |         ArgumentNullException.ThrowIfNull(mapping);
367 | 
368 |         Option<TResult> result;
369 | 
370 |         if (HasValue)
371 |         {
372 |             result = mapping(Value, Success);
373 | 
374 |             result.MatchNone(e =>
375 |             {
376 |                 if (subsequentError != null)
377 |                 {
378 |                     result = Optional.None<TResult>(subsequentError.CausedBy(e));
379 |                 }
380 |             });
381 |         }
382 |         else
383 |         {
384 |             result = Optional.None<TResult>(subsequentError != null ? subsequentError.CausedBy(Error) : Error);
385 |         }
386 | 
387 |         return result;
388 |     }
389 | 
390 |     /// <summary>
391 |     /// If the current optional has a value, sets its success reason as the direct reason to the specified subsequent success reason.
392 |     /// </summary>
393 |     /// <param name="success">The current optional's success reason will be set as the cause of the specified success reason.</param>
394 |     public Option<TValue> FlatMapSome(Success success)
395 |     {
396 |         ArgumentNullException.ThrowIfNull(success);
397 | 
398 |         if (!HasValue)
399 |         {
400 |             return Optional.Some(Value, success.EnabledBy(this));
401 |         }
402 | 
403 |         return this;
404 |     }
405 | 
406 |     /// <summary>
407 |     /// If the current optional is empty, sets its error as the direct reason to the specified subsequent error.
408 |     /// </summary>
409 |     /// <param name="subsequentError">If the current optional is empty, sets its error as the direct reason to the specified subsequent error.</param>
410 |     public Option<TValue> FlatMapNone(Error subsequentError)
411 |     {
412 |         ArgumentNullException.ThrowIfNull(subsequentError);
413 | 
414 |         if (!HasValue)
415 |         {
416 |             return Optional.None<TValue>(subsequentError.CausedBy(this));
417 |         }
418 | 
419 |         return this;
420 |     }
421 | 
422 |     /// <summary>
423 |     /// Empties an optional and attaches an error object if the specified predicate is not satisfied.
424 |     /// </summary>
425 |     /// <param name="predicate">The predicate.</param>
426 |     /// <param name="predicateFailure">An error object describing why the predicate failed.<para>Example: "Value must be greater than 10. Was 2."</para></param>
427 |     /// <param name="subsequentError">If the current optional is empty, sets its error as the direct reason to the specified subsequent error.</param>
428 |     /// <returns>The filtered optional.</returns>
429 |     public Option<TValue> Filter(Predicate<TValue> predicate, Error predicateFailure, Error subsequentError = null)
430 |     {
431 |         return Filter(predicate, _ => predicateFailure, subsequentError);
432 |     }
433 | 
434 |     /// <summary>
435 |     /// Empties an optional and attaches an error object if the specified predicate is not satisfied.
436 |     /// </summary>
437 |     /// <param name="predicate">The predicate.</param>
438 |     /// <param name="predicateFailure">An error object describing why the predicate failed.<para>Example: "Value must be greater than 10. Was 2."</para></param>
439 |     /// <param name="subsequentError">If the current optional is empty, sets its error as the direct reason to the specified subsequent error.</param>
440 |     /// <returns>The filtered optional.</returns>
441 |     public Option<TValue> Filter(Predicate<TValue> predicate, Func<TValue, Error> predicateFailure, Error subsequentError = null)
442 |     {
443 |         ArgumentNullException.ThrowIfNull(predicate);
444 | 
445 |         foreach (var (value, _) in this)
446 |         {
447 |             return predicate(value) ? this : Optional.None<TValue>(predicateFailure(value));
448 |         }
449 | 
450 |         return Optional.None<TValue>(subsequentError?.CausedBy(Error) ?? Error);
451 |     }
452 | 
453 |     /// <summary>
454 |     /// Empties an optional and attaches an error object if the value is null.
455 |     /// </summary>
456 |     /// <param name="error">An error object with data describing why the optional is missing its value.</param>
457 |     /// <returns>The filtered optional.</returns>
458 |     public Option<TValue> NotNull(Error error)
459 |     {
460 |         ArgumentNullException.ThrowIfNull(error);
461 | 
462 |         return HasValue && Value == null ? Optional.None<TValue>(error) : this;
463 |     }
464 | 
465 | 
466 |     /// <summary>
467 |     /// Returns a string that represents the current optional.
468 |     /// </summary>
469 |     /// <returns>A string that represents the current optional.</returns>
470 |     public override string ToString()
471 |     {
472 |         if (HasValue)
473 |         {
474 |             string valueString;
475 | 
476 |             if (Value == null)
477 |             {
478 |                 valueString = "null";
479 |             }
480 |             else
481 |             {
482 |                 if (Value is ICollection c) valueString = $"Count = {c.Count}";
483 |                 else if (typeof(TValue) == typeof(IReadOnlyCollection<>))
484 |                 {
485 |                     var valueType = Value.GetType().GetInterfaces().Single(i => i == typeof(IReadOnlyCollection<>));
486 | 
487 |                     valueString = $"Count = {valueType.GetProperty("Count")!.GetValue(valueType)}";
488 |                 }
489 |                 else
490 |                 {
491 |                     valueString = Value.ToString();
492 |                 }
493 |             }
494 | 
495 |             return $"Some({valueString}{(Success.Message != "" || Success.Metadata.Count > 0 ? $" | {Success}" : "")})";
496 |         }
497 | 
498 |         return $"None{(Error != null ? $"(Error={Error})" : "")}";
499 |     }
500 | }
501 | 


--------------------------------------------------------------------------------
/tests/Ultimately.Tests/EitherTests.cs:
--------------------------------------------------------------------------------
  1 | namespace Ultimately.Tests;
  2 | 
  3 | using Reasons;
  4 | 
  5 | using Xunit;
  6 | 
  7 | using System;
  8 | 
  9 | public class EitherTests
 10 | {
 11 |     [Fact]
 12 |     public void Either_CreateAndCheckExistence()
 13 |     {
 14 |         var noneStruct = Optional.None<int>("ex");
 15 |         var noneNullable = Optional.None<int?>("ex");
 16 |         var noneClass = Optional.None<string>("ex");
 17 | 
 18 |         Assert.False(noneStruct.HasValue);
 19 |         Assert.False(noneNullable.HasValue);
 20 |         Assert.False(noneClass.HasValue);
 21 | 
 22 |         var someStruct = 1.Some();
 23 |         var someNullable = Optional.Some<int?>(1);
 24 |         var someNullableEmpty = Optional.Some<int?>(null);
 25 |         var someClass = Optional.Some("1");
 26 |         var someClassNull = Optional.Some<string>(null);
 27 | 
 28 |         Assert.True(someStruct.HasValue);
 29 |         Assert.True(someNullable.HasValue);
 30 |         Assert.True(someNullableEmpty.HasValue);
 31 |         Assert.True(someClass.HasValue);
 32 |         Assert.True(someClassNull.HasValue);
 33 |     }
 34 | 
 35 |     [Fact]
 36 |     public void Either_CheckContainment()
 37 |     {
 38 |         var noneStruct = Optional.None<int>("ex");
 39 |         var noneNullable = Optional.None<int?>("ex");
 40 |         var noneClass = Optional.None<string>("ex");
 41 | 
 42 |         Assert.False(noneStruct.Contains(0));
 43 |         Assert.False(noneNullable.Contains(null));
 44 |         Assert.False(noneClass.Contains(null));
 45 | 
 46 |         Assert.False(noneStruct.Exists(val => true));
 47 |         Assert.False(noneNullable.Exists(val => true));
 48 |         Assert.False(noneClass.Exists(val => true));
 49 | 
 50 |         var someStruct = Optional.Some(1);
 51 |         var someNullable = Optional.Some<int?>(1);
 52 |         var someNullableEmpty = Optional.Some<int?>(null);
 53 |         var someClass = Optional.Some("1");
 54 |         var someClassNull = Optional.Some<string>(null);
 55 | 
 56 |         Assert.True(someStruct.Contains(1));
 57 |         Assert.True(someNullable.Contains(1));
 58 |         Assert.True(someNullableEmpty.Contains(null));
 59 |         Assert.True(someClass.Contains("1"));
 60 |         Assert.True(someClassNull.Contains(null));
 61 | 
 62 |         Assert.True(someStruct.Exists(val => val == 1));
 63 |         Assert.True(someNullable.Exists(val => val == 1));
 64 |         Assert.True(someNullableEmpty.Exists(val => val == null));
 65 |         Assert.True(someClass.Exists(val => val == "1"));
 66 |         Assert.True(someClassNull.Exists(val => val == null));
 67 | 
 68 |         Assert.False(someStruct.Contains(-1));
 69 |         Assert.False(someNullable.Contains(-1));
 70 |         Assert.False(someNullableEmpty.Contains(1));
 71 |         Assert.False(someClass.Contains("-1"));
 72 |         Assert.False(someClassNull.Contains("1"));
 73 | 
 74 |         Assert.False(someStruct.Exists(val => val != 1));
 75 |         Assert.False(someNullable.Exists(val => val != 1));
 76 |         Assert.False(someNullableEmpty.Exists(val => val != null));
 77 |         Assert.False(someClass.Exists(val => val != "1"));
 78 |         Assert.False(someClassNull.Exists(val => val != null));
 79 |     }
 80 | 
 81 |     [Fact]
 82 |     public void Either_StringRepresentation()
 83 |     {
 84 |         Assert.Equal("None(Error='No value')", Optional.None<int>("No value").ToString());
 85 |         Assert.Equal("None(Error='No value')", Optional.None<int>(Error.Create("No value")).ToString());
 86 |         Assert.Equal("None(Error='No value', Caused by=Exception: 'An exception occurred')", Optional.None<int>("No value", new Exception("An exception occurred")).ToString());
 87 | 
 88 |         Assert.Equal("Some(null)", Optional.Some<int?>(null).ToString());
 89 |         Assert.Equal("Some(null)", Optional.Some<string>(null).ToString());
 90 | 
 91 |         Assert.Equal("Some(1)", Optional.Some(1).ToString());
 92 |         Assert.Equal("Some(1)", Optional.Some<int?>(1).ToString());
 93 |         Assert.Equal("Some(1)", Optional.Some("1").ToString());
 94 | 
 95 | 
 96 |         var now = DateTime.Now;
 97 | 
 98 |         Assert.Equal($"Some({now})", Optional.Some(now).ToString());
 99 |         Assert.Equal($"Some({now} | 'Success')", Optional.Some(now, "Success").ToString());
100 |         Assert.Equal($"Some({now} | 'Success')", Optional.Some(now, Success.Create("Success")).ToString());
101 |     }
102 | 
103 |     [Fact]
104 |     public void Either_GetValue()
105 |     {
106 |         var noneStruct = Optional.None<int>("ex");
107 |         var noneStructNullable = Optional.None<int?>("ex");
108 |         var noneReferenceType = Optional.None<string>("ex");
109 | 
110 |         Assert.Equal(-1, noneStruct.ValueOr(-1));
111 |         Assert.Equal(-1, noneStructNullable.ValueOr(-1));
112 |         Assert.Equal("-1", noneReferenceType.ValueOr("-1"));
113 | 
114 |         var someStruct = Optional.Some(1);
115 |         var someNullableStruct = Optional.Some<int?>(1);
116 |         var someNullableStructNull = Optional.Some<int?>(null);
117 |         var someReferenceType = Optional.Some("1");
118 |         var someReferenceTypeNull = Optional.Some<string>(null);
119 | 
120 |         Assert.Equal(1, someStruct.ValueOr(-1));
121 |         Assert.Equal(1, someNullableStruct.ValueOr(-1));
122 |         Assert.Null(someNullableStructNull.ValueOr(-1));
123 |         Assert.Equal("1", someReferenceType.ValueOr("-1"));
124 |         Assert.Null(someReferenceTypeNull.ValueOr("-1"));
125 |     }
126 | 
127 |     [Fact]
128 |     public void Either_GetValueLazy()
129 |     {
130 |         var noneStruct = Optional.None<int>("ex");
131 |         var noneStructNullable = Optional.None<int?>("ex");
132 |         var noneReferenceType = Optional.None<string>("ex");
133 | 
134 |         Assert.Equal(-1, noneStruct.ValueOr(() => -1));
135 |         Assert.Equal(noneStructNullable.ValueOr(() => -1), -1);
136 |         Assert.Equal("-1", noneReferenceType.ValueOr(() => "-1"));
137 | 
138 | 
139 |         var someStruct = Optional.Some(1);
140 |         var someNullable = Optional.Some<int?>(1);
141 |         var someNullableEmpty = Optional.Some<int?>(null);
142 |         var someClass = Optional.Some("1");
143 |         var someClassNull = Optional.Some<string>(null);
144 | 
145 |         Assert.Equal(1, someStruct.ValueOr(() => -1));
146 |         Assert.Equal(1, someNullable.ValueOr(() => -1));
147 |         Assert.Null(someNullableEmpty.ValueOr(() => -1));
148 |         Assert.Equal("1", someClass.ValueOr(() => "-1"));
149 |         Assert.Null(someClassNull.ValueOr(() => "-1"));
150 | 
151 |         Assert.Equal(1, someStruct.ValueOr(() =>
152 |         {
153 |             Assert.Fail();
154 | 
155 |             return -1;
156 |         }));
157 | 
158 |         Assert.Equal(1, someNullable.ValueOr(() =>
159 |         {
160 |             Assert.Fail();
161 | 
162 |             return -1;
163 |         }));
164 | 
165 |         Assert.Null(someNullableEmpty.ValueOr(() =>
166 |         {
167 |             Assert.Fail();
168 | 
169 |             return -1;
170 |         }));
171 | 
172 |         Assert.Equal("1", someClass.ValueOr(() =>
173 |         {
174 |             Assert.Fail();
175 | 
176 |             return "-1";
177 |         }));
178 | 
179 |         Assert.Null(someClassNull.ValueOr(() =>
180 |         {
181 |             Assert.Fail();
182 | 
183 |             return "-1";
184 |         }));
185 |     }
186 | 
187 |     [Fact]
188 |     public void Either_AlternativeValue()
189 |     {
190 |         var noneStruct = Optional.None<int>("ex");
191 |         var noneNullable = Optional.None<int?>("ex");
192 |         var noneClass = Optional.None<string>("ex");
193 | 
194 |         Assert.False(noneStruct.HasValue);
195 |         Assert.False(noneNullable.HasValue);
196 |         Assert.False(noneClass.HasValue);
197 | 
198 |         var someStruct = noneStruct.Or(1);
199 |         var someNullable = noneNullable.Or(1);
200 |         var someClass = noneClass.Or("1");
201 | 
202 |         Assert.True(someStruct.HasValue);
203 |         Assert.True(someNullable.HasValue);
204 |         Assert.True(someClass.HasValue);
205 | 
206 |         Assert.Equal(1, someStruct.ValueOr(-1));
207 |         Assert.Equal(1, someNullable.ValueOr(-1));
208 |         Assert.Equal("1", someClass.ValueOr("-1"));
209 |     }
210 | 
211 |     [Fact]
212 |     public void Either_AlternativeOption()
213 |     {
214 |         var noneStruct = Optional.None<int>("ex");
215 |         var noneNullable = Optional.None<int?>("ex");
216 |         var noneClass = Optional.None<string>("ex");
217 | 
218 |         Assert.False(noneStruct.HasValue);
219 |         Assert.False(noneNullable.HasValue);
220 |         Assert.False(noneClass.HasValue);
221 | 
222 |         var noneStruct2 = noneStruct.Else(Optional.None<int>("ex2"));
223 |         var noneNullable2 = noneNullable.Else(Optional.None<int?>("ex2"));
224 |         var noneClass2 = noneClass.Else(Optional.None<string>("ex2"));
225 | 
226 |         Assert.False(noneStruct2.HasValue);
227 |         Assert.False(noneNullable2.HasValue);
228 |         Assert.False(noneClass2.HasValue);
229 | 
230 |         var someStruct = noneStruct.Else(1.Some());
231 |         var someNullable = noneNullable.Else(Optional.Some<int?>(1));
232 |         var someClass = noneClass.Else("1".Some());
233 | 
234 |         Assert.True(someStruct.HasValue);
235 |         Assert.True(someNullable.HasValue);
236 |         Assert.True(someClass.HasValue);
237 | 
238 |         Assert.Equal(1, someStruct.ValueOr(-1));
239 |         Assert.Equal(1, someNullable.ValueOr(-1));
240 |         Assert.Equal("1", someClass.ValueOr("-1"));
241 |     }
242 | 
243 |     [Fact]
244 |     public void Either_AlternativeValueLazy()
245 |     {
246 |         var noneStruct = Optional.None<int>("ex");
247 |         var noneNullable = Optional.None<int?>("ex");
248 |         var noneClass = Optional.None<string>("ex");
249 | 
250 |         Assert.False(noneStruct.HasValue);
251 |         Assert.False(noneNullable.HasValue);
252 |         Assert.False(noneClass.HasValue);
253 | 
254 |         var someStruct = noneStruct.Or(() => 1);
255 |         var someNullable = noneNullable.Or(() => 1);
256 |         var someClass = noneClass.Or(() => "1");
257 | 
258 |         Assert.True(someStruct.HasValue);
259 |         Assert.True(someNullable.HasValue);
260 |         Assert.True(someClass.HasValue);
261 | 
262 |         Assert.Equal(1, someStruct.ValueOr(() => -1));
263 |         Assert.Equal(1, someNullable.ValueOr(() => -1));
264 |         Assert.Equal("1", someClass.ValueOr(() => "-1"));
265 | 
266 |         someStruct.Or(() =>
267 |         {
268 |             Assert.Fail();
269 | 
270 |             return -1;
271 |         });
272 | 
273 |         someNullable.Or(() =>
274 |         {
275 |             Assert.Fail();
276 | 
277 |             return -1;
278 |         });
279 | 
280 |         someClass.Or(() =>
281 |         {
282 |             Assert.Fail();
283 | 
284 |             return "-1";
285 |         });
286 |     }
287 | 
288 |     [Fact]
289 |     public void Either_AlternativeOptionLazy()
290 |     {
291 |         var noneStruct = Optional.None<int>("ex");
292 |         var noneNullable = Optional.None<int?>("ex");
293 |         var noneClass = Optional.None<string>("ex");
294 | 
295 |         Assert.False(noneStruct.HasValue);
296 |         Assert.False(noneNullable.HasValue);
297 |         Assert.False(noneClass.HasValue);
298 | 
299 |         var noneStruct2 = noneStruct.Else(() => Optional.None<int>("ex2"));
300 |         var noneNullable2 = noneNullable.Else(() => Optional.None<int?>("ex2"));
301 |         var noneClass2 = noneClass.Else(() => Optional.None<string>("ex2"));
302 | 
303 |         Assert.False(noneStruct2.HasValue);
304 |         Assert.False(noneNullable2.HasValue);
305 |         Assert.False(noneClass2.HasValue);
306 | 
307 |         var someStruct = noneStruct.Else(() => 1.Some());
308 |         var someNullable = noneNullable.Else(() => Optional.Some<int?>(1));
309 |         var someClass = noneClass.Else(() => "1".Some());
310 | 
311 |         Assert.True(someStruct.HasValue);
312 |         Assert.True(someNullable.HasValue);
313 |         Assert.True(someClass.HasValue);
314 | 
315 |         Assert.Equal(1, someStruct.ValueOr(() => -1));
316 |         Assert.Equal(1, someNullable.ValueOr(() => -1));
317 |         Assert.Equal("1", someClass.ValueOr(() => "-1"));
318 | 
319 |         someStruct.Else(() =>
320 |         {
321 |             Assert.Fail();
322 | 
323 |             return (-1).Some();
324 |         });
325 |         someNullable.Else(() =>
326 |         {
327 |             Assert.Fail();
328 | 
329 |             return Optional.Some<int?>(-1);
330 |         });
331 |         someClass.Else(() =>
332 |         {
333 |             Assert.Fail();
334 | 
335 |             return "-1".Some();
336 |         });
337 |     }
338 | 
339 |     [Fact]
340 |     public void Either_CreateExtensions()
341 |     {
342 |         var none = Optional.None<int>("ex");
343 |         var some = 1.Some();
344 | 
345 |         Assert.Equal(-1, none.ValueOr(-1));
346 |         Assert.Equal(1, some.ValueOr(-1));
347 | 
348 |         var noneLargerThanTen = 1.SomeWhen(x => x > 10, "ex");
349 |         var someLargerThanTen = 20.SomeWhen(x => x > 10, "ex");
350 | 
351 |         Assert.Equal(-1, noneLargerThanTen.ValueOr(-1));
352 |         Assert.Equal(20, someLargerThanTen.ValueOr(-1));
353 | 
354 |         var noneNotNull = (null as string).SomeNotNull("ex");
355 |         var someNotNull = "1".SomeNotNull("ex");
356 | 
357 |         Assert.Equal("-1", noneNotNull.ValueOr("-1"));
358 |         Assert.Equal("1", someNotNull.ValueOr("-1"));
359 | 
360 |         var noneNullableNotNull = (null as int?).SomeNotNull("ex");
361 |         var someNullableNotNull = (1 as int?).SomeNotNull("ex");
362 | 
363 |         Assert.IsType<int>(noneNullableNotNull.ValueOr(-1));
364 |         Assert.IsType<int>(someNullableNotNull.ValueOr(-1));
365 |         Assert.Equal(-1, noneNullableNotNull.ValueOr(-1));
366 |         Assert.Equal(1, someNullableNotNull.ValueOr(-1));
367 | 
368 |         var noneFromNullable = (null as int?).ToOption("ex");
369 |         var someFromNullable = (1 as int?).ToOption("ex");
370 | 
371 |         Assert.IsType<int>(noneFromNullable.ValueOr(-1));
372 |         Assert.IsType<int>(someFromNullable.ValueOr(-1));
373 |         Assert.Equal(-1, noneFromNullable.ValueOr(-1));
374 |         Assert.Equal(1, someFromNullable.ValueOr(-1));
375 |     }
376 | 
377 |     [Fact]
378 |     public void Either_Matching()
379 |     {
380 |         var none = Optional.None<string>("ex");
381 |         var some = "val".Some();
382 | 
383 |         var failure = none.Match(
384 |                                  some: val => val,
385 |                                  none: ex => ex.Message
386 |                                 );
387 | 
388 |         var success = some.Match(
389 |                                  some: val => val,
390 |                                  none: e => e.Message
391 |                                 );
392 | 
393 |         Assert.Equal("ex", failure);
394 |         Assert.Equal("val", success);
395 | 
396 |         var hasMatched = false;
397 |         none.Match(
398 |                    some: val => Assert.Fail(),
399 |                    none: e => hasMatched = e.Message == "ex"
400 |                   );
401 | 
402 |         Assert.True(hasMatched);
403 | 
404 |         hasMatched = false;
405 |         some.Match(
406 |                    some: val => hasMatched = val == "val",
407 |                    none: e => Assert.Fail()
408 |                   );
409 | 
410 |         Assert.True(hasMatched);
411 | 
412 |         none.MatchSome(val => Assert.Fail());
413 | 
414 | 
415 |         hasMatched = false;
416 |         some.MatchSome(val => hasMatched = val == "val");
417 | 
418 |         Assert.True(hasMatched);
419 | 
420 |         some.MatchNone(e => Assert.Fail());
421 | 
422 |         hasMatched = false;
423 |         none.MatchNone(e => hasMatched = e.Message == "ex");
424 | 
425 |         Assert.True(hasMatched);
426 |     }
427 | 
428 |     [Fact]
429 |     public void Either_Transformation()
430 |     {
431 |         var none = Optional.None<string>("ex");
432 |         var some = "val".Some();
433 | 
434 |         var noneNull = Optional.None<string>("ex");
435 |         var someNull = (null as string).Some();
436 | 
437 |         var noneUpper = none.Map(x => x.ToUpper());
438 |         var someUpper = some.Map(x => x.ToUpper());
439 | 
440 |         Assert.False(noneUpper.HasValue);
441 |         Assert.True(someUpper.HasValue);
442 |         Assert.Equal("ex", noneUpper.ValueOr("ex"));
443 |         Assert.Equal("VAL", someUpper.ValueOr("ex"));
444 | 
445 |         var noneNotNull = none.FlatMap(x => x.SomeNotNull("ex1"));
446 |         var someNotNull = some.FlatMap(x => x.SomeNotNull("ex1"));
447 |         var noneNullNotNull = noneNull.FlatMap(x => x.SomeNotNull("ex1"));
448 |         var someNullNotNull = someNull.FlatMap(x => x.SomeNotNull("ex1"));
449 | 
450 |         Assert.False(noneNotNull.HasValue);
451 |         Assert.True(someNotNull.HasValue);
452 |         Assert.False(noneNullNotNull.HasValue);
453 |         Assert.False(someNullNotNull.HasValue);
454 |         Assert.Equal("ex", noneNotNull.Match(val => val, e => e.Message));
455 |         Assert.Equal("val", someNotNull.Match(val => val, e => e.Message));
456 |         Assert.Equal("ex", noneNullNotNull.Match(val => val, e => e.Message));
457 |         Assert.Equal("ex1", someNullNotNull.Match(val => val, e => e.Message));
458 |     }
459 | 
460 |     [Fact]
461 |     public void Either_Flatten()
462 |     {
463 |         var noneNone = Optional.None<Option<string>>("1");
464 |         var someNone = Optional.Some<Option<string>>(Optional.None<string>("2"));
465 |         var someSome = Optional.Some<Option<string>>(Optional.Some("a"));
466 | 
467 |         Assert.False(noneNone.HasValue);
468 |         Assert.False(noneNone.Flatten().HasValue);
469 |         noneNone.Flatten().Match(
470 |                                  some: val => Assert.Fail(),
471 |                                  none: e => Assert.Equal("1", e.Message)
472 |                                 );
473 | 
474 | 
475 |         Assert.True(someNone.HasValue);
476 |         Assert.False(someNone.Flatten().HasValue);
477 |         someNone.Flatten().Match(
478 |                                  some: val => Assert.Fail(),
479 |                                  none: e => Assert.Equal("2", e.Message)
480 |                                 );
481 | 
482 |         Assert.True(someSome.HasValue);
483 |         Assert.True(someSome.Flatten().HasValue);
484 |         Assert.Equal("a", someSome.Flatten().ValueOr("b"));
485 |     }
486 | 
487 |     [Fact]
488 |     public void Either_Filtering()
489 |     {
490 |         var none = Optional.None<string>("ex");
491 |         var some = "val".Some();
492 | 
493 |         var noneNotVal = none.Filter(x => x != "val", Error.Create("ex1"));
494 |         var someNotVal = some.Filter(x => x != "val", Error.Create("ex1"));
495 |         var noneVal = none.Filter(x => x == "val", Error.Create("ex1"));
496 |         var someVal = some.Filter(x => x == "val", Error.Create("ex1"));
497 | 
498 |         Assert.False(noneNotVal.HasValue);
499 |         Assert.False(someNotVal.HasValue);
500 |         Assert.False(noneVal.HasValue);
501 |         Assert.True(someVal.HasValue);
502 |         Assert.Equal("ex", noneNotVal.Match( val => val, e => e.Message));
503 |         Assert.Equal("ex1", someNotVal.Match( val => val, e => e.Message));
504 |         Assert.Equal("ex", noneVal.Match( val => val, e => e.Message));
505 |         Assert.Equal("val", someVal.Match( val => val, e => e.Message));
506 | 
507 |         var noneFalse = none.Filter(x => false, Error.Create("ex1"));
508 |         var someFalse = some.Filter(x => false, Error.Create("ex1"));
509 |         var noneTrue = none.Filter(x => true, Error.Create("ex1"));
510 |         var someTrue = some.Filter(x => true, Error.Create("ex1"));
511 | 
512 |         Assert.False(noneFalse.HasValue);
513 |         Assert.False(someFalse.HasValue);
514 |         Assert.False(noneTrue.HasValue);
515 |         Assert.True(someTrue.HasValue);
516 |         Assert.Equal("ex", noneFalse.Match( val => val, e => e.Message));
517 |         Assert.Equal("ex1", someFalse.Match( val => val, e => e.Message));
518 |         Assert.Equal("ex", noneTrue.Match( val => val, e => e.Message));
519 |         Assert.Equal("val", someTrue.Match( val => val, e => e.Message));
520 | 
521 |         var someNull = Optional.Some(null as string);
522 |         Assert.True(someNull.HasValue);
523 |         Assert.False(someNull.NotNull(Error.Create("ex")).HasValue);
524 | 
525 |         var someNullableNull = Optional.Some(null as int?);
526 |         Assert.True(someNullableNull.HasValue);
527 |         Assert.False(someNullableNull.NotNull(Error.Create("-1")).HasValue);
528 | 
529 |         var someStructNull = Optional.Some(default(int));
530 |         Assert.True(someStructNull.HasValue);
531 |         Assert.True(someStructNull.NotNull(Error.Create("-1")).HasValue);
532 | 
533 |         Assert.True(some.HasValue);
534 |         Assert.True(some.NotNull(Error.Create("ex")).HasValue);
535 | 
536 |         Assert.False(none.HasValue);
537 |         Assert.False(none.NotNull(Error.Create("ex1")).HasValue);
538 | 
539 | 
540 |         var noneFalseWithReason = none.Filter(x => false, Error.Create("ex1"), "Predicate execution skipped");
541 |         Assert.Equal("Predicate execution skipped", noneFalseWithReason.Match(val => val, e => e.Message));
542 |         Assert.NotEqual("ex1", noneFalseWithReason.Match(val => val, e => e.Message));
543 |     }
544 | 
545 |     [Fact]
546 |     public void Either_ToEnumerable()
547 |     {
548 |         var none = Optional.None<string>("ex");
549 |         var some = "a".Some();
550 | 
551 |         var noneAsEnumerable = none.ToEnumerable();
552 |         var someAsEnumerable = some.ToEnumerable();
553 | 
554 |         foreach (var _ in noneAsEnumerable)
555 |         {
556 |             Assert.Fail();
557 |         }
558 | 
559 |         var count = 0;
560 | 
561 |         foreach (var value in someAsEnumerable)
562 |         {
563 |             Assert.Equal("a", value);
564 | 
565 |             count += 1;
566 |         }
567 | 
568 |         Assert.Equal(1, count);
569 | 
570 |         foreach (var value in someAsEnumerable)
571 |         {
572 |             Assert.Equal("a", value);
573 | 
574 |             count += 1;
575 |         }
576 | 
577 |         Assert.Equal(2, count);
578 | 
579 |         Assert.Empty(noneAsEnumerable);
580 |         Assert.Single(someAsEnumerable);
581 |     }
582 | 
583 |     [Fact]
584 |     public void Either_Enumerate()
585 |     {
586 |         var none = Optional.None<string>("ex");
587 |         var some = "a".Some();
588 | 
589 |         foreach (var _ in none)
590 |         {
591 |             Assert.Fail();
592 |         }
593 | 
594 |         var count = 0;
595 | 
596 |         foreach (var (value, _) in some)
597 |         {
598 |             Assert.Equal("a", value);
599 | 
600 |             count += 1;
601 |         }
602 | 
603 |         Assert.Equal(1, count);
604 | 
605 |         foreach (var (value, _) in some)
606 |         {
607 |             Assert.Equal("a", value);
608 | 
609 |             count += 1;
610 |         }
611 | 
612 |         Assert.Equal(2, count);
613 |     }
614 | }
615 | 


--------------------------------------------------------------------------------
/tests/Ultimately.Tests/CollectionTests.cs:
--------------------------------------------------------------------------------
  1 | namespace Ultimately.Tests;
  2 | 
  3 | using Collections;
  4 | using Reasons;
  5 | 
  6 | using Xunit;
  7 | 
  8 | using System;
  9 | using System.Collections;
 10 | using System.Collections.Generic;
 11 | using System.Linq;
 12 | using System.Threading.Tasks;
 13 | 
 14 | public class CollectionTests
 15 | {
 16 |     [Fact]
 17 |     public void Collections_Enumerable_ValuesEither()
 18 |     {
 19 |         var list1 = new List<Option<string>>
 20 |                     {
 21 |                         Optional.Some("a"),
 22 |                         Optional.None<string>("error"),
 23 |                         Optional.None<string>("error"),
 24 |                         Optional.Some("b"),
 25 |                         Optional.None<string>("error"),
 26 |                         Optional.Some("c"),
 27 |                     };
 28 |         var list1Expected = new List<string> { "a", "b", "c" };
 29 | 
 30 |         var list2 = Enumerable.Empty<Option<string>>();
 31 |         var list2Expected = new List<string>();
 32 | 
 33 |         var list3 = new List<Option<string>> { "a".Some() };
 34 |         var list3Expected = new List<string> { "a" };
 35 | 
 36 |         var list4 = new List<Option<string>> { Optional.None<string>("error") };
 37 |         var list4Expected = new List<string>();
 38 | 
 39 | 
 40 |         Assert.Equal(list1.Values().ToList(), list1Expected);
 41 |         Assert.Equal(list2.Values().ToList(), list2Expected);
 42 |         Assert.Equal(list3.Values().ToList(), list3Expected);
 43 |         Assert.Equal(list4.Values().ToList(), list4Expected);
 44 |     }
 45 | 
 46 |     [Fact]
 47 |     public void Collections_Enumerable_ExceptionsEither()
 48 |     {
 49 |         var list1 = new List<Option<string>>
 50 |                     {
 51 |                         Optional.None<string>("a"),
 52 |                         Optional.Some("value"),
 53 |                         Optional.Some("value"),
 54 |                         Optional.None<string>("b"),
 55 |                         Optional.Some("value"),
 56 |                         Optional.None<string>("c"),
 57 |                     };
 58 | 
 59 |         var list1Expected = new List<string> { "a", "b", "c" };
 60 | 
 61 |         var list2 = new List<Option<string>>();
 62 |         var list2Expected = new List<string>();
 63 | 
 64 |         var list3 = new List<Option<string>> { Optional.None<string>("a") };
 65 |         var list3Expected = new List<string> { "a" };
 66 | 
 67 |         var list4 = new List<Option<string>> { Optional.Some("error") };
 68 |         var list4Expected = new List<string>();
 69 | 
 70 | 
 71 |         Assert.Equal(list1.Errors().Select(e => e.Message).ToList(), list1Expected);
 72 |         Assert.Equal(list2.Errors().Select(e => e.Message).ToList(), list2Expected);
 73 |         Assert.Equal(list3.Errors().Select(e => e.Message).ToList(), list3Expected);
 74 |         Assert.Equal(list4.Errors().Select(e => e.Message).ToList(), list4Expected);
 75 |     }
 76 | 
 77 |     [Fact]
 78 |     public void Collections_Enumerable_FirstOrNone()
 79 |     {
 80 |         var full = Enumerable.Range(0, 100);
 81 |         var empty = Enumerable.Empty<int>();
 82 |         var single = Enumerable.Repeat(0, 1);
 83 | 
 84 |         FirstOperator(full, single, empty);
 85 | 
 86 |         var fullList = Enumerable.Range(0, 100).ToList();
 87 |         var emptyList = Enumerable.Empty<int>().ToList();
 88 |         var singleList = Enumerable.Repeat(0, 1).ToList();
 89 | 
 90 |         FirstOperator(fullList, singleList, emptyList);
 91 | 
 92 |         var fullReadOnlyList = new TestReadOnlyList<int>(Enumerable.Range(0, 100).ToList());
 93 |         var emptyReadOnlyList = new TestReadOnlyList<int>(Enumerable.Empty<int>().ToList());
 94 |         var singleReadOnlyList = new TestReadOnlyList<int>(Enumerable.Repeat(0, 1).ToList());
 95 | 
 96 |         FirstOperator(fullReadOnlyList, singleReadOnlyList, emptyReadOnlyList);
 97 |     }
 98 | 
 99 |     [Fact]
100 |     public void Collections_Enumerable_LastOrNone()
101 |     {
102 |         var full = Enumerable.Range(0, 100);
103 |         var empty = Enumerable.Empty<int>();
104 |         var single = Enumerable.Repeat(0, 1);
105 | 
106 |         LastOperator(full, single, empty);
107 | 
108 |         var fullList = Enumerable.Range(0, 100).ToList();
109 |         var emptyList = Enumerable.Empty<int>().ToList();
110 |         var singleList = Enumerable.Repeat(0, 1).ToList();
111 | 
112 |         LastOperator(fullList, singleList, emptyList);
113 | 
114 |         var fullReadOnlyList = new TestReadOnlyList<int>(Enumerable.Range(0, 100).ToList());
115 |         var emptyReadOnlyList = new TestReadOnlyList<int>(Enumerable.Empty<int>().ToList());
116 |         var singleReadOnlyList = new TestReadOnlyList<int>(Enumerable.Repeat(0, 1).ToList());
117 | 
118 |         LastOperator(fullReadOnlyList, singleReadOnlyList, emptyReadOnlyList);
119 |     }
120 | 
121 |     [Fact]
122 |     public void Collections_Enumerable_SingleOrNone()
123 |     {
124 |         var full = Enumerable.Range(0, 100);
125 |         var empty = Enumerable.Empty<int>();
126 |         var single = Enumerable.Repeat(0, 1);
127 | 
128 |         SingleOperator(full, single, empty);
129 | 
130 |         var fullList = Enumerable.Range(0, 100).ToList();
131 |         var emptyList = Enumerable.Empty<int>().ToList();
132 |         var singleList = Enumerable.Repeat(0, 1).ToList();
133 | 
134 |         SingleOperator(fullList, singleList, emptyList);
135 | 
136 |         var fullReadOnlyList = new TestReadOnlyList<int>(Enumerable.Range(0, 100).ToList());
137 |         var emptyReadOnlyList = new TestReadOnlyList<int>(Enumerable.Empty<int>().ToList());
138 |         var singleReadOnlyList = new TestReadOnlyList<int>(Enumerable.Repeat(0, 1).ToList());
139 | 
140 |         SingleOperator(fullReadOnlyList, singleReadOnlyList, emptyReadOnlyList);
141 |     }
142 | 
143 |     [Fact]
144 |     public void Collections_Enumerable_ElementAtOrNone()
145 |     {
146 |         var full = Enumerable.Range(0, 100);
147 |         var empty = Enumerable.Empty<int>();
148 |         var single = Enumerable.Repeat(0, 1);
149 | 
150 |         ElementAtOperator(full, single, empty);
151 | 
152 |         var fullList = Enumerable.Range(0, 100).ToList();
153 |         var emptyList = Enumerable.Empty<int>().ToList();
154 |         var singleList = Enumerable.Repeat(0, 1).ToList();
155 | 
156 |         ElementAtOperator(fullList, singleList, emptyList);
157 | 
158 |         var fullReadOnlyList = new TestReadOnlyList<int>(Enumerable.Range(0, 100).ToList());
159 |         var emptyReadOnlyList = new TestReadOnlyList<int>(Enumerable.Empty<int>().ToList());
160 |         var singleReadOnlyList = new TestReadOnlyList<int>(Enumerable.Repeat(0, 1).ToList());
161 | 
162 |         ElementAtOperator(fullReadOnlyList, singleReadOnlyList, emptyReadOnlyList);
163 |     }
164 | 
165 |     [Fact]
166 |     public void Collections_Dictionary_GetValueOrNone()
167 |     {
168 |         var dictionaryA = Enumerable.Range(50, 50).ToDictionary(i => i, i => i.ToString());
169 |         var excludedKeysA = Enumerable.Range(-50, 50);
170 |         GetValueOperator(new TestReadOnlyDictionary<int, string>(dictionaryA), excludedKeysA);
171 |         GetValueOperator(new TestDictionary<int, string>(dictionaryA), excludedKeysA);
172 |         GetValueOperator(dictionaryA.ToList(), excludedKeysA);
173 | 
174 |         var dictionaryB = new Dictionary<string, Guid>
175 |                           {
176 |                               { "a", Guid.NewGuid() },
177 |                               { "b", Guid.NewGuid() },
178 |                               { "c", Guid.NewGuid() },
179 |                               { "d", Guid.NewGuid() },
180 |                               { "e", Guid.NewGuid() },
181 |                           };
182 |         var excludedKeysB = new List<string> { "h", "i", "j", "k" };
183 | 
184 |         GetValueOperator(new TestReadOnlyDictionary<string, Guid>(dictionaryB), excludedKeysB);
185 |         GetValueOperator(new TestDictionary<string, Guid>(dictionaryB), excludedKeysB);
186 |         GetValueOperator(dictionaryB.ToList(), excludedKeysB);
187 |     }
188 | 
189 |     [Fact]
190 |     public void Collections_Reduce()
191 |     {
192 |         const int value = 42;
193 | 
194 |         var validationRules1 = new List<LazyOption>
195 |                                {
196 |                                    Optional.Lazy(() => (value & 1) == 1, Success.Create("Value is odd"), "Value must be odd"),
197 |                                    Optional.Lazy(() => value / 2 == 77, Success.Create("Value divided by two is 77"), "Value divided by two must equal 77"),
198 |                                };
199 | 
200 |         var validationRulesReduced1 = validationRules1.Reduce();
201 | 
202 |         Assert.False(validationRulesReduced1.IsSuccessful);
203 |         validationRulesReduced1.Match(
204 |                                       some: _ => Assert.Fail(),
205 |                                       none: e => Assert.Equal("Value must be odd", e.Message)
206 |                                      );
207 | 
208 | 
209 |         var validationRules2 = new List<LazyOption>
210 |                                {
211 |                                    Optional.Lazy(() => value % 2 == 0, Success.Create("Value is even"), "Value must be even"),
212 |                                    Optional.Lazy(() => value == 42, Success.Create("Value is 42"), "Value must be equal to 42"),
213 |                                };
214 | 
215 |         var validationRulesReduced2 = validationRules2.Reduce();
216 | 
217 |         Assert.True(validationRulesReduced2.IsSuccessful);
218 | 
219 | 
220 | 
221 |         var validationRules3 = new List<LazyOption>
222 |                                {
223 |                                    Optional.Lazy(() => value % 2 == 0, Success.Create("Value is even"), "Value must be even"),
224 |                                    Optional.Lazy(() => value / 2 == 77, Success.Create("Value divided by two is 77"), "Value divided by two must equal 77"),
225 |                                };
226 | 
227 |         var validationRulesReduced3 = validationRules3.Reduce();
228 | 
229 |         Assert.False(validationRulesReduced3.IsSuccessful);
230 |         validationRulesReduced3.Match(
231 |                                       some: _ => Assert.Fail(),
232 |                                       none: e => Assert.Equal("Value divided by two must equal 77", e.Message)
233 |                                      );
234 | 
235 | 
236 | 
237 | 
238 |         bool validationRun1 = false, validationRun2 = false, validationRun3 = false, validationRun4 = false;
239 | 
240 |         var validationRules4 = new List<LazyOption>
241 |                                {
242 |                                    Optional.Lazy(() =>
243 |                                    {
244 |                                        validationRun1 = true;
245 | 
246 |                                        return (value & 1) == 1;
247 |                                    }, Success.Create("SUCCESS"), "ERROR"),
248 | 
249 |                                    Optional.Lazy(() =>
250 |                                    {
251 |                                        validationRun2 = true;
252 | 
253 |                                        return (value & 1) == 1;
254 |                                    }, Success.Create("SUCCESS"), "ERROR"),
255 | 
256 |                                    Optional.Lazy(() =>
257 |                                    {
258 |                                        validationRun3 = true;
259 | 
260 |                                        return (value & 1) == 1;
261 |                                    }, Success.Create("SUCCESS"), "ERROR"),
262 | 
263 |                                    Optional.Lazy(() =>
264 |                                    {
265 |                                        validationRun4 = true;
266 | 
267 |                                        return (value & 1) == 1;
268 |                                    }, Success.Create("SUCCESS"), "ERROR"),
269 |                                };
270 | 
271 |         var validationRulesReduced4 = validationRules4.Reduce();
272 | 
273 |         Assert.False(validationRulesReduced4.IsSuccessful);
274 | 
275 |         Assert.True(validationRun1);
276 |         Assert.False(validationRun2);
277 |         Assert.False(validationRun3);
278 |         Assert.False(validationRun4);
279 |     }
280 | 
281 |     [Fact]
282 |     public async Task Collections_Reduce_Async()
283 |     {
284 |         const int value = 42;
285 | 
286 |         var validationRules1 = new List<LazyOptionAsync>
287 |                                {
288 |                                    Optional.LazyAsync(() => Task.FromResult((value & 1) == 1), Success.Create("Value is odd"), "Value must be odd"),
289 |                                    Optional.LazyAsync(() => Task.FromResult(value / 2 == 77), Success.Create("Value divided by two is 77"), "Value divided by two must equal 77"),
290 |                                };
291 | 
292 |         var validationRulesReduced1 = await validationRules1.ReduceAsync();
293 | 
294 |         Assert.False(validationRulesReduced1.IsSuccessful);
295 |         validationRulesReduced1.Match(
296 |                                       some: _ => Assert.Fail(),
297 |                                       none: e => Assert.Equal("Value must be odd", e.Message)
298 |                                      );
299 | 
300 | 
301 |         var validationRules2 = new List<LazyOptionAsync>
302 |                                {
303 |                                    Optional.LazyAsync(() => Task.FromResult(value % 2 == 0), Success.Create("Value is even"), "Value must be even"),
304 |                                    Optional.LazyAsync(() => Task.FromResult(value == 42), Success.Create("Value is 42"), "Value must be equal to 42"),
305 |                                };
306 | 
307 |         var validationRulesReduced2 = await validationRules2.ReduceAsync();
308 | 
309 |         Assert.True(validationRulesReduced2.IsSuccessful);
310 | 
311 | 
312 | 
313 |         var validationRules3 = new List<LazyOptionAsync>
314 |                                {
315 |                                    Optional.LazyAsync(() => Task.FromResult(value % 2 == 0), Success.Create("Value is even"), "Value must be even"),
316 |                                    Optional.LazyAsync(() => Task.FromResult(value / 2 == 77), Success.Create("Value divided by two is 77"), "Value divided by two must equal 77"),
317 |                                };
318 | 
319 |         var validationRulesReduced3 = await validationRules3.ReduceAsync();
320 | 
321 |         Assert.False(validationRulesReduced3.IsSuccessful);
322 |         validationRulesReduced3.Match(
323 |                                       some: _ => Assert.Fail(),
324 |                                       none: e => Assert.Equal("Value divided by two must equal 77", e.Message)
325 |                                      );
326 | 
327 | 
328 | 
329 |         bool validationRun1 = false, validationRun2 = false, validationRun3 = false, validationRun4 = false;
330 | 
331 |         var validationRules4 = new List<LazyOptionAsync>
332 |                                {
333 |                                    Optional.LazyAsync(() =>
334 |                                    {
335 |                                        validationRun1 = true;
336 | 
337 |                                        return Task.FromResult((value & 1) == 1);
338 |                                    }, Success.Create("SUCCESS"), "ERROR"),
339 | 
340 |                                    Optional.LazyAsync(() =>
341 |                                    {
342 |                                        validationRun2 = true;
343 | 
344 |                                        return Task.FromResult((value & 1) == 1);
345 |                                    }, Success.Create("SUCCESS"), "ERROR"),
346 | 
347 |                                    Optional.LazyAsync(() =>
348 |                                    {
349 |                                        validationRun3 = true;
350 | 
351 |                                        return Task.FromResult((value & 1) == 1);
352 |                                    }, Success.Create("SUCCESS"), "ERROR"),
353 | 
354 |                                    Optional.LazyAsync(() =>
355 |                                    {
356 |                                        validationRun4 = true;
357 | 
358 |                                        return Task.FromResult((value & 1) == 1);
359 |                                    }, Success.Create("SUCCESS"), "ERROR"),
360 |                                };
361 | 
362 |         var validationRulesReduced4 = await validationRules4.ReduceAsync();
363 | 
364 |         Assert.False(validationRulesReduced4.IsSuccessful);
365 | 
366 |         Assert.True(validationRun1);
367 |         Assert.False(validationRun2);
368 |         Assert.False(validationRun3);
369 |         Assert.False(validationRun4);
370 |     }
371 | 
372 | 
373 |     private static void FirstOperator(IEnumerable<int> full, IEnumerable<int> single, IEnumerable<int> empty)
374 |     {
375 |         var fullList = full.ToList();
376 |         var singleList = single.ToList();
377 |         var emptyList = empty.ToList();
378 | 
379 |         Assert.True(fullList.FirstOrNone().HasValue);
380 |         Assert.True(fullList.FirstOrNone(x => x == 50).HasValue);
381 |         Assert.False(fullList.FirstOrNone(x => x == -1).HasValue);
382 | 
383 |         Assert.Equal(fullList.FirstOrNone().ValueOr(-1), fullList.First());
384 |         Assert.Equal(50, fullList.FirstOrNone(x => x == 50).ValueOr(-1));
385 |         Assert.Equal(51, fullList.FirstOrNone(x => x > 50).ValueOr(-1));
386 |         Assert.Equal(fullList.FirstOrNone(x => x < 50).ValueOr(-1), fullList.First());
387 | 
388 |         Assert.True(singleList.FirstOrNone().HasValue);
389 |         Assert.True(singleList.FirstOrNone(x => x == 0).HasValue);
390 |         Assert.False(singleList.FirstOrNone(x => x == -1).HasValue);
391 |         Assert.Equal(singleList.FirstOrNone().ValueOr(-1), singleList.First());
392 | 
393 |         Assert.False(emptyList.FirstOrNone().HasValue);
394 |         Assert.False(emptyList.FirstOrNone(x => x == 50).HasValue);
395 |     }
396 | 
397 |     private static void LastOperator(IEnumerable<int> full, IEnumerable<int> single, IEnumerable<int> empty)
398 |     {
399 |         var fullList = full.ToList();
400 |         var singleList = single.ToList();
401 |         var emptyList = empty.ToList();
402 | 
403 |         Assert.True(fullList.LastOrNone().HasValue);
404 |         Assert.True(fullList.LastOrNone(x => x == 50).HasValue);
405 |         Assert.False(fullList.LastOrNone(x => x == -1).HasValue);
406 | 
407 |         Assert.Equal(fullList.LastOrNone().ValueOr(-1), fullList.Last());
408 |         Assert.Equal(50, fullList.LastOrNone(x => x == 50).ValueOr(-1));
409 |         Assert.Equal(fullList.LastOrNone(x => x > 50).ValueOr(-1), fullList.Last());
410 |         Assert.Equal(49, fullList.LastOrNone(x => x < 50).ValueOr(-1));
411 | 
412 |         Assert.True(singleList.LastOrNone().HasValue);
413 |         Assert.True(singleList.LastOrNone(x => x == 0).HasValue);
414 |         Assert.False(singleList.LastOrNone(x => x == -1).HasValue);
415 |         Assert.Equal(singleList.LastOrNone().ValueOr(-1), singleList.Last());
416 | 
417 |         Assert.False(emptyList.LastOrNone().HasValue);
418 |         Assert.False(emptyList.LastOrNone(x => x == 50).HasValue);
419 |     }
420 | 
421 |     private static void SingleOperator(IEnumerable<int> full, IEnumerable<int> single, IEnumerable<int> empty)
422 |     {
423 |         var fullList = full.ToList();
424 |         var singleList = single.ToList();
425 |         var emptyList = empty.ToList();
426 | 
427 |         Assert.False(fullList.SingleOrNone().HasValue);
428 |         Assert.True(fullList.SingleOrNone(x => x == 50).HasValue);
429 |         Assert.False(fullList.SingleOrNone(x => x == -1).HasValue);
430 |         Assert.False(fullList.SingleOrNone(x => x > 50).HasValue);
431 |         Assert.False(fullList.SingleOrNone(x => x < 50).HasValue);
432 |         Assert.Equal(50, fullList.SingleOrNone(x => x == 50).ValueOr(-1));
433 | 
434 |         Assert.True(singleList.SingleOrNone().HasValue);
435 |         Assert.True(singleList.SingleOrNone(x => x == 0).HasValue);
436 |         Assert.False(singleList.SingleOrNone(x => x == -1).HasValue);
437 |         Assert.Equal(singleList.SingleOrNone().ValueOr(-1), singleList.Single());
438 | 
439 |         Assert.False(emptyList.SingleOrNone().HasValue);
440 |         Assert.False(emptyList.SingleOrNone(x => x == 50).HasValue);
441 |     }
442 | 
443 |     private static void ElementAtOperator(IEnumerable<int> full, IEnumerable<int> single, IEnumerable<int> empty)
444 |     {
445 |         var fullList = full.ToList();
446 |         var singleList = single.ToList();
447 | 
448 |         Assert.False(fullList.ElementAtOrNone(-1).HasValue);
449 |         Assert.False(fullList.ElementAtOrNone(fullList.Count).HasValue);
450 | 
451 |         for (var i = 0; i < fullList.Count; i++)
452 |         {
453 |             Assert.True(fullList.ElementAtOrNone(i).HasValue);
454 |             Assert.Equal(fullList.ElementAtOrNone(i).ValueOr(-1), fullList.ElementAt(i));
455 |         }
456 | 
457 |         Assert.True(singleList.ElementAtOrNone(0).HasValue);
458 |         Assert.False(singleList.ElementAtOrNone(2).HasValue);
459 |         Assert.False(singleList.ElementAtOrNone(-1).HasValue);
460 |         Assert.Equal(singleList.ElementAtOrNone(0).ValueOr(-1), singleList.Single());
461 | 
462 |         Assert.False(empty.ElementAtOrNone(0).HasValue);
463 |     }
464 | 
465 |     private static void GetValueOperator<TKey, TValue>(IEnumerable<KeyValuePair<TKey, TValue>> dictionary, IEnumerable<TKey> excludedKeys)
466 |     {
467 |         var keyValuePairsList = dictionary.ToList();
468 | 
469 |         foreach (var pair in keyValuePairsList)
470 |         {
471 |             Assert.True(keyValuePairsList.GetValueOrNone(pair.Key).HasValue);
472 |             Assert.Equal(keyValuePairsList.GetValueOrNone(pair.Key).ValueOr(default(TValue)), pair.Value);
473 |         }
474 | 
475 |         foreach (var key in excludedKeys)
476 |         {
477 |             Assert.False(keyValuePairsList.GetValueOrNone(key).HasValue);
478 |         }
479 |     }
480 | 
481 |     private class TestReadOnlyDictionary<TKey, TValue>(Dictionary<TKey, TValue> dictionary) : IReadOnlyDictionary<TKey, TValue>
482 |     {
483 |         public TValue this[TKey key] => dictionary[key];
484 |         public int Count => dictionary.Count;
485 |         public IEnumerable<TKey> Keys => dictionary.Keys;
486 |         public IEnumerable<TValue> Values => dictionary.Values;
487 |         public bool ContainsKey(TKey key) => dictionary.ContainsKey(key);
488 |         public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator() => dictionary.GetEnumerator();
489 |         public bool TryGetValue(TKey key, out TValue value) => dictionary.TryGetValue(key, out value);
490 |         IEnumerator IEnumerable.GetEnumerator() => ((IEnumerable)dictionary).GetEnumerator();
491 |     }
492 | 
493 |     private class TestReadOnlyList<TValue>(List<TValue> list) : IReadOnlyList<TValue>
494 |     {
495 |         public TValue this[int index] => list[index];
496 |         public int Count => list.Count;
497 |         public IEnumerator<TValue> GetEnumerator() => list.GetEnumerator();
498 |         IEnumerator IEnumerable.GetEnumerator() => ((IEnumerable)list).GetEnumerator();
499 |     }
500 | 
501 |     private class TestDictionary<TKey, TValue>(Dictionary<TKey, TValue> dictionary) : IDictionary<TKey, TValue>
502 |     {
503 |         private ICollection<KeyValuePair<TKey, TValue>> Collection => dictionary;
504 | 
505 |         public TValue this[TKey key]
506 |         {
507 |             get => dictionary[key];
508 |             set => dictionary[key] = value;
509 |         }
510 | 
511 |         public int Count => dictionary.Count;
512 |         public bool IsReadOnly => Collection.IsReadOnly;
513 |         public ICollection<TKey> Keys => dictionary.Keys;
514 |         public ICollection<TValue> Values => dictionary.Values;
515 |         public void Add(KeyValuePair<TKey, TValue> item) => Collection.Add(item);
516 |         public void Add(TKey key, TValue value) => dictionary.Add(key, value);
517 |         public void Clear() => Collection.Clear();
518 |         public bool Contains(KeyValuePair<TKey, TValue> item) => dictionary.Contains(item);
519 |         public bool ContainsKey(TKey key) => dictionary.ContainsKey(key);
520 |         public void CopyTo(KeyValuePair<TKey, TValue>[] array, int arrayIndex) => Collection.CopyTo(array, arrayIndex);
521 |         public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator() => dictionary.GetEnumerator();
522 |         public bool Remove(KeyValuePair<TKey, TValue> item) => Collection.Remove(item);
523 |         public bool Remove(TKey key) => dictionary.Remove(key);
524 |         public bool TryGetValue(TKey key, out TValue value) => dictionary.TryGetValue(key, out value);
525 |         IEnumerator IEnumerable.GetEnumerator() => ((IEnumerable)dictionary).GetEnumerator();
526 |     }
527 | }
528 | 


--------------------------------------------------------------------------------