meta data for this page
  •  

Z0ne.Maybe Documentation

Z0ne.Maybe Logo
Z0ne.Maybe brings one feature of functional programming into the world of C# and .Net: Optionals.
They are most often referred to as option or maybe.

This library is being developed alongside a product with my company and will be extended alongside real world requirements of our repertoire.

The changelog is available here.

Getting Started

  1. Add the Z0ne.Maybe nuget package to your project.
  2. Create an instance by calliing Maybe.A, Maybe.Just, or Maybe.Nothing.
  3. Use the provided methods (e.g.: Match, Do, DoWhenNothing, DoWhenJust) to work with the instance.
  4. For additional async functionality, add the Z0ne.Maybe.Async nuget package to your project.

Common Tasks

Creating new instances

// create a just instance when val is not null
var a = Maybe.A(val);
 
// always create a value that is just
var b = Maybe.Just(val);
 
// always create a value that is nothing
var c = Maybe.Nothing<T>();
 
// create an instance when val is not null (extension method)
var d = val.Maybe();
 
// create a just instance when val is matching the predicate (extension method)
var e = val.MaybeWhen(val => true);

Run code based on state

var doJust = innerValue => Consloe.WriteLine($"Maybe is {innerValue}");
var doNothing => () => Console.WriteLine("Maybe is nothing");
 
// run callback based on state
maybe.Do(doJust, doNothing);
 
// run only when maybe is just
maybe.DoWhenJust(doJust);
 
// run only when maybe is nothing
maybe.DoWhenNothing(doNothing);
 
// run callback, discard result and continue with original value
maybe.Tap(innerMaybe => {});

Convert Code

// convert maybe to a different type
var a = maybe.Match(val => val.ToString(), () => string.Empty);
 
// convert maybe to a different maybe (nothing will stay nothing)
var b = maybe.Select(val => val.ToString());
 
// returns a bool whether the predicate matches
var c = maybe.Exists(val => val == 1);
 
// returns the maybe nothing if the predicate doesn't match, otherwise the original maybe
var d = maybe.Where(val => false);
 
// collapse to the innermost value (if maybe's are nested just return the inner most maybe)
var e = maybe.Flatten();

Provide alternatives

// use the return of the function if maybe is nothing
var a = maybe.Else(() => 1);
 
// use the provided value if maybe is nothing (prefer Else if you have to calculate the value)
var b = maybe.Or(1);

Extract values

// convert maybe to native nullable (recommended not to use)
var a = maybe.ToNullable();
 
// get the inner value if not nothing, otherwise throw MaybeNothingException
var b = maybe.Unwrap();
 
// get the inner value, or the provided alternative value (prefer OrElse if you have to calculate the value)
var c = maybe.UnwrapOr(1);
 
// get the inner value, or the return value of the provided function
var d = maybe.UnwrapOrElse(() => 1);
 
// get the inner value, or create a new instance (only available when the inner type is a class with a new() constructor)
var e = maybe.UnwrapOrNew();

Collection and Queryable extensions

There are methods that are similar to *OrDefault that return a Maybe instead of a nullable value.
The following methods are available: MaybeFirst, MaybeLast, MaybeSingle, MaybeElementAt.

A List<KeyValuePair<TKey, TValue>> (e.g. Dictionary<TKey, TValue>) has the MaybeGetValue method that wraps the TryGetValue method.
IEnumerable<Maybe<T>> also has the Values method, that will return a list of IEnumerable<T> for all entries that are not nothing.

Async

Many methods listed above exist as async methods. They need the Z0ne.Maybe.Async nuget package.

Every method must be awaited, The Suffix of the method name describe its operation:

Await: The maybe is not wrapped in a Task, but the callbacks are async functions.

Async: The maybe is wrapped in a Task, but the callbacks are sync functions and operate on the result of the task.

AsyncAwait: The maybe is wrapped in a Task, AND the callbacks are async functions: They operate on the result of the task and don't need to be awaited on.

API Docs

Either use your IDE provided utilities or use e.g. fuget to fetch all code documentation.

Source and Contributors

Z0ne.Maybe is licensed under BSD-3-Clause license, as detailed in the license found in the repository.
The repository containing the source code for this library can be found on Gitea.
Contributions are welcomed.