LunarDoggo.Optionals 1.0.1

LunarDoggo.Optionals

This library was inspired by a project at university where we had to implement an extension to Java optionals. C# provides an alternative to optionals with the null-conditional (?) and null-coalescing (??) operators, but there is no easy way to return error messages to calling methods by using these operators without throwing Exceptions or returning custom objects that can contain a value or an error message.

This library's main goal is to provide an easy way for bubbling exceptions and messages up to calling methods without needing an uncountable amount of try-catch-blocks and if-statements. To achieve this goal, the library distinguishes between three kinds of optionals:

• those which contain values
• those which contain only a message
• those which contain a message and an exception

Usage

1. Creating optionals

using LunarDoggo.Optionals;
[...]
void SomeMethod()
{
    //Create an optional containing a value
    IOptional<int> value = Optional.OfValue<int>(12);
    
    //Create an optional containing a message
    IOptional<int> message = Optional.OfMessage<int>("Insert your message here");
    
    //Create an optional containing an exception
    IOptional<int> exception = Optional.OfException<int>(new ArgumentException("Some message"));
    
    //Create an optional containing an exception and a custom message
    IOptional<int> exception = Optional.OfException<int>(new ArgumentException("Some exception"), "Custom message");
    
    //Create an optional from a collection of optionals of the same generic type
    IOptional<IEnumerable<int>> values = Optional.OfOptionals<IEnumerable<int>>(new[] { Optional.OfValue<int>(1), [...] });
}

Optional.OfMessage<T>(string), Optional.OfException<T>(Exception) and Optional.OfException<T>(Exception, string) are mainly used when mapping an optional using the methods IOptional<T>.FlatMap<S>(Func<T, IOptional<S>>) and IOptional<T>.SafeFlatMap<S, V>(Func<T, IOptional<S>>) in order to

2. Map between different types of optionals

using LunarDoggo.Optionals;
[...]
void SomeMethod()
{
    IOptional<string> value = Optional.Of<string>("123");
    
    //Map to int
    IOptional<int> map = value.Map(_str => Int32.Parse(_str)); //does not catch exceptions
    IOptional<int> safeMap = value.SafeMap<int, FormatException>(_str => Int32.Parse(_str)); //catches Exceptions of the provided type and returns an IOptional<T> containing the caught Exception if one was caught
    
    //FlatMap to int; useful for example for validation
    IOptional<int> flatMap = value.FlatMap(_str => {
        int i = Int32.Parse(_str);
        if(i > 100)
            return Optional.OfMessage<int>("Expected a value less or equal to 100");
        return Optional.OfValue<int>(i);
    }); //does not catch exceptions
    IOptional<int> safeFlatMap = value.FlatMap<int, FormatException>(_str => {
        int i = Int32.Parse(_str);
        if(i > 100)
            return Optional.OfMessage<int>("Expected a value less or equal to 100");
        return Optional.OfValue<int>(i);
    }); //catches Exceptions of the provided type and returns an IOptional<T> containing the caught Exception if one was caught
}

Please be aware that optionals that contain a message or an Exception will always return an optional containing the same message or Exception, the provided mapping functions will not be executed

3. Apply changes to an optional:

using LunarDoggo.Optionals;
[...]
void SomeMethod()
{
    //Apply something to the contained value (only changes the contained value if the optional contains an object of a mutable reference type)
    IOptional<int[]> values = Optional.OfValue<int[]>(new int[] { 1, 2, 3 }).Apply(_values => _values[1] = 10); //sets the second value in the array contained in the optional to 10
}

Please be aware that optionals that contain a message or an Exception will not execute the provided action

4. Extract values from an optional without using the Value property:

using LunarDoggo.Optionals;
[...]
void SomeMethod()
{
    IOptional<string> value = Optional.Of<string>("123");
    
    //Convert an optional to a string
    string intValue = value.ToString(_str => _str + "!"); //returns "123!" in this example
    string message = Optional.OfMessage<int>("Some message").ToString(_i => _i); //returns "Some message"
    
    //Get the contained value or an alternative
    string val1 = value.OrElse("Empty"); //Returns "123" in this example
    int val2 = Optional.OfMessage<int>("Message").OrElse(123); //returns 123
    int val3 = Optional.OfMessage<int>("Message").OrElse(() => 321); //returns 321
}

API

Methods and properties provided by every IOptional<T> object: Method/Property | Description ---|--- bool HasValue { get; } | Returns whether the optional contains a value T Value { get; } | Returns the contained value if it is present otherwise, a NotSupportedException is thrown bool HasMessage { get; } | Returns whether the optional contains a message string Message { get; } | Returns the contained message if it is present, otherwise a NotSupportedException is thrown bool HasException { get; } | Returns whether the optional contains an Exception IOptional<S> SafeFlatMap<S, V : Exception>(Func<T, IOptional<S>>) | maps this optional to an optional of type S. Use this version if you want to catch a specific kind of exception IOptional<S> SafeFlatMap(Func<T, IOptional<S>>) | maps this optional to an optional of type S. Use this version if you want to catch any kind of exception IOptional<S> FlatMap(Func<T, IOptional<S>>) | maps this optional to an optional of type S IOptional<S> SafeMap<S, V : Exception>(Func<T, S>) | maps this optional to an optional of type S. Use this version if you want to catch a specific kind of exception IOptional<S> SafeMap(Func<T, S>) | maps this optional to an optional of type S. Use this version if you want to catch any kind of exception IOptional<S> Map(Func<T, S>) | maps this optional to an optional of type S IOptional<T> Map(Action<T>) | applies an Action<T> to the contained value IOptional<T> IfHasException(Action<Exception>) | the provided action is executed if the optional contains an exception IOptional<T> IfHasMessage(Action<string>) | the provided action is executed if the optional contains a message IOptional<T> IfHasValue(Action<T>) | the provided action is executed if the optional contains a value string ToString(Func<T, string>) | converts the contained value to a string if it is present, otherwise the contained message is returned T OrElseThrow(Exception) | Returnes the contained value if it is present, otherwise the provided exception is thrown T OrElse(Func<T>) | Returnes the contained value if it is present, otherwise the result of provided function returning an object of type T is returned T OrElse(T) | Returnes the contained value if it is present, otherwise the provided parameter of type T is returned

Note: the methods IfHasValue and Apply functionally behave the same way, but IfHasValue is intended to call other code if a value is contained, whereas Apply is intended to be used to alter the contained value itself

Methods provided by the static class Optional: Method | Description ---|--- IOptional<T> OfValue<T>(T) | Creates a new IOptional<T> containing the provided value IOptional<T> OfMessage<T>(string) | Creates a new IOptional<T> containing the provided message IOptional<T> OfException<T>(Exception) | Creates a new IOptional<T> containing the provided Exception IOptional<T> OfException<T>(Exception, string) | Creates a new IOptional<T> containing the provided Exception and custom message IOptional<IEnumerable<T>> OfOptionals<T>(IEnumerable<IOptional<T>>) | Creates a new IOptional<IEnumerable<T>> containing the value of all provided IOptional<T> objects. If any of the provided objects contains an Exception, the resulting optional contains all Exceptions, if any of the provided objects contains a message, all Messages will be concatenated to a single one and an optional containing this message will be returned instead

Extension methods provided by the static class Optional: Extension method | Description ---|--- IOptional<IEnumerable<T>> Filter<T>(Func<T, bool>) | Filters all values contained in the optional and returns an optional that only contains the items that match the provided filter IOptional<S> ForEach<S, T>(Action<T>) where S : IEnumerable<T> | Applies the provided action to every item of the optional's contained collection IOptional<S> Convert<T, S, V>(Func<T, S>) | Returns an optional that contains the same values as the provided optional but with another kind of collection derived from IEnumerable<V> IOptional<S> Cast<T, S, V>() | Returns an optional that contains the same collection as the calling optional, but with a type cast applied to it