====== Z0ne.Maybe Documentation ======
{{:z0ne.maybe:logo.png?75 |Z0ne.Maybe Logo}}
[[gt>z0ne/Z0ne.Maybe|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 [[https://tiplu.de|company]] and will be extended alongside real world requirements of our repertoire. 

The changelog is available [[z0ne.maybe:changelog|here]].

===== Getting Started =====
  - Add the [[nuget>Z0ne.Maybe|Z0ne.Maybe nuget package]] to your project.
  - Create an instance by calliing ''Maybe.A'', ''Maybe.Just'', or ''Maybe.Nothing''.
  - Use the provided methods (e.g.: ''Match'', ''Do'', ''DoWhenNothing'', ''DoWhenJust'') to work with the instance.
  - For additional async functionality, add the [[nuget>Z0ne.Maybe.Async|Z0ne.Maybe.Async nuget package]] to your project.

==== Common Tasks ====
=== Creating new instances ===

<code csharp>
// 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);
</code>

=== Run code based on state ===

<code csharp>
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 => {});
</code>

=== Convert Code ===

<code csharp>
// 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();
</code>

=== Provide alternatives ===

<code csharp>
// 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);
</code>

=== Extract values ===

<code csharp>
// 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();
</code>

=== 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 [[nuget>Z0ne.Maybe.Async|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. [[http://fuget.org/packages/Z0ne.Maybe|fuget]] to fetch all code documentation.

==== Source and Contributors ====
Z0ne.Maybe is licensed under [[spdx>BSD-3-Clause]] license, as detailed in the [[gt>z0ne/Z0ne.Maybe/src/branch/master/LICENSE|license]] found in the repository. 
The repository containing the source code for this library can be found [[gt>z0ne/Z0ne.Maybe|on Gitea]].
Contributions are welcomed.