### Pretty

### Differencing

Location | Feature | Description
---------|---------|------------
`Core` | `Patch` | Uses patch-theory to efficiently calculate the difference (`Patch.diff(list1, list2)`) between two collections of `A` and build a patch which can be applied (`Patch.apply(patch, list)`) to one to make the other (think git diff).

### Make C# better

Location | Feature | Description
---------|---------|------------
`Core` | `Nullable` extensions | [Extension methods for `Nullable`](https://louthy.github.io/language-ext/LanguageExt.Core/Monads/Alternative%20Value%20Monads/Nullable/index.html) that make it into a functor, applicative, foldable, iterable and a monad
`Core` | `Task` extensions | [Extension methods for `Task`](https://louthy.github.io/language-ext/LanguageExt.Core/Concurrency/Task/index.html) that make it into a functor, applicative, foldable, iterable and a monad
`Core` | [Improved lambda type inference](https://louthy.github.io/language-ext/LanguageExt.Core/Prelude/Lambda%20function%20inference/index.html) | `var add = fun( (int x, int y) => x + y)`
`Core` | Currying | [Translate the evaluation of a function that takes multiple arguments into a sequence of functions, each with a single argument](https://louthy.github.io/language-ext/LanguageExt.Core/Prelude/Currying%20and%20Partial%20Application/index.html)
`Core` | Partial application | [the process of fixing a number of arguments to a function, producing another function of smaller arity](https://louthy.github.io/language-ext/LanguageExt.Core/Prelude/Currying%20and%20Partial%20Application/index.html)
`Core` | [`IQueryable` extensions](https://louthy.github.io/language-ext/LanguageExt.Core/Extensions/index.html) |
`Core` | [`IObservable` extensions](https://louthy.github.io/language-ext/LanguageExt.Core/Extensions/index.html) |
`Core` | Memoization | [An optimization technique used primarily to speed up programs by storing the results of expensive function calls and returning the cached result when the same inputs occur again](https://louthy.github.io/language-ext/LanguageExt.Core/Prelude/Memoizing/index.html)

This library started out trying to deal with issues in C#, that after using Haskell and F# started to frustrate me:

## Poor tuple support

> NOTE: Since writing this, the csharplang team have improved tuple support in C#

I've been crying out for proper tuple support for ages. When this library was created we were no closer (C# 6).
The standard way of creating them is ugly `Tuple.Create(foo,bar)` compared to functional languages where the syntax is often
`(foo,bar)` and to consume them you must work with the standard properties of `Item1`...`ItemN`.

```C#
var ab = Tuple("a","b");
```

Now isn't that nice?

Consuming the tuple is now handled using `Map`, which projects the `Item1`...`ItemN` onto a lambda function (or action):

```C#
var name = Tuple("Paul","Louth");
var res = name.Map( (first, last) => $"{first} {last}");
```
Or, you can use a more functional approach:
```C#
var name = Tuple("Paul","Louth");
var res = map( name, (first, last) => $"{first} {last}");
```
This allows the tuple properties to have names, and it also allows for fluent handling of functions that return tuples.

If you are using C#7+ then you'll know that the new `Tuple` type is `ValueTuple`. Just like with `Tuple`, language-ext
adds many extensions to the standard BCL `ValueTuple`.

For example:

```C#
var abc = ('a', 'b').Add('c'); // ('a', 'b', 'c')
var abcd = ('a', 'b').Add('c').Add('d'); // ('a', 'b', 'c', 'd')
var abcd5 = ('a', 'b').Add('c').Add('d').Add(5); // ('a', 'b', 'c', 'd', 5)

var sum = (1, 2, 3).Sum(); // 6
var product = (2, 4, 8).Product(); // 64
var flag = ("one", "two", "three").Contains("one"); // true
var str = ("Hello", " ", "World").Concat(); // "Hello World"
var list = (List(1, 2, 3), List(4, 5, 6)).Concat, Lst>(); // [1,2,3,4,5,6]
```

## Null reference problem

> NOTE: Since writing this, the csharplang team have improved null support in C#

`null` must be [the biggest mistake](https://www.infoq.com/presentations/Null-References-The-Billion-Dollar-Mistake-Tony-Hoare/) in the whole of computer language history. I realise the original designers
of C# had to make pragmatic decisions, it's a shame this one slipped through though. So, what to do about the
"null problem"?

`null` is often used to indicate _no value_; the method called can't produce a value of the type it said
it was going to produce, and therefore it gives you "nothing". The thing is that when _no value_ is passed to
the consuming code, it gets assigned to a variable of type T, the same type that the function said it was going
to return, except this variable now has a timebomb in it. You must continually check if the value is `null`, if
it's passed around it must be checked too.

As we all know it's only a matter of time before a null reference bug crops up because the variable wasn't
checked. It puts C# in the realm of the dynamic languages, where you can't trust the value you're being given.

Functional languages use what's known as an _option type_. In F# it's called `Option`, in Haskell it's called
`Maybe`. In the next section we'll see how it's used.

## Option

`Option` works in a very similar way to `Nullable`, except it works with all types rather than just value
types. It's a `struct` and therefore can't be `null`. An instance can be created by either calling `Some(value)`,
which represents a positive "I have a value" response, or `None`, which is the equivalent of returning `null`.

So why is it any better than returning `T` and using `null`? It seems we can have a non-value response again
right? Yes, that's true, however you're forced to acknowledge that fact and to write code to handle both possible
outcomes because you can't get to the underlying value without acknowledging the possibility of the two states
that the value could be in. This bulletproofs your code. You're also explicitly telling any other programmers that "this method might not return a value, so make sure you deal with that". This explicit declaration is very
powerful.

This is how you create an `Option`:

```C#
var optional = Some(123);
```
To access the value you must check that it's valid first:

```C#
int x = optional.Match(
Some: v => v * 2,
None: () => 0
);
```
An alternative (functional) way of matching is this:

```C#
int x = match( optional,
Some: v => v * 2,
None: () => 0 );
```
Yet another alternative ("fluent") matching method is this:
```C#
int x = optional
.Some( v => v * 2 )
.None( () => 0 );
```
So choose your preferred method and stick with it. It's probably best not to mix styles.

There are also some helper functions to work with default `None` values; you won't see a `.Value` or a
`GetValueOrDefault()` anywhere in this library. This is because `.Value` puts us right back to where we started, and
you may as well not use `Option` in that case. `GetValueOrDefault()` is also just as bad because it can return `null`
for reference types, and depends on how well defined the `struct` type is you're working with.

However, clearly there will be times when you don't need to do anything with the `Some` case. Also, sometimes you just want some code to execute in the `Some` case and not the
`None` case:

```C#
// Returns the Some case 'as is' and 10 in the None case
int x = optional.IfNone(10);

// As above, but invokes a Func to return a valid value for x
int x = optional.IfNone(() => GetAlternative());

// Invokes an Action if in the Some state.
optional.IfSome(x => Console.WriteLine(x));
```
Of course there are functional versions of the fluent version above:
```C#
int x = ifNone(optional, 10);
int x = ifNone(optional, () => GetAlternative());
ifSome(optional, x => Console.WriteLine(x));
```
To smooth out the process of returning `Option` types from methods there are some implicit conversion
operators and constructors:

```C#
// Implicitly converts the integer to a Some of int
Option GetValue()
{
return 1000;
}

// Implicitly converts to a None of int
Option GetValue()
{
return None;
}

// Will handle either a None or a Some returned
Option GetValue(bool select) =>
select
? Some(1000)
: None;

// Explicitly converts a null value to None and a non-null value to Some(value)
Option GetValue()
{
string value = GetValueFromNonTrustedApi();
return Optional(value);
}

// Implicitly converts a null value to None and a non-null value to Some(value)
Option GetValue()
{
string value = GetValueFromNonTrustedApi();
return value;
}
```

It's actually nearly impossible to get a `null` out of a function, even if the `T` in `Option` is a
reference type and you write `Some(null)`. Firstly, it won't compile, but you might think you can do this:

```C#
private Option GetStringNone()
{
string nullStr = null;
return Some(nullStr);
}
```
That will compile, but at runtime will throw a `ValueIsNullException`. If you do either of these (below)
you'll get a `None`.

```C#
private Option GetStringNone()
{
string nullStr = null;
return nullStr;
}

private Option GetStringNone()
{
string nullStr = null;
return Optional(nullStr);
}

```
These are the coercion rules:

Converts from | Converts to
--------------|-------------
`x` | `Some(x)`
`null` | `None`
`None` | `None`
`Some(x)` | `Some(x)`
`Some(null)` | `ValueIsNullException`
`Some(None)` | `Some(None)`
`Some(Some(x))` | `Some(Some(x))`
`Some(Nullable null)` | `ValueIsNullException`
`Some(Nullable x)` | `Some(x)`
`Optional(x)` | `Some(x)`
`Optional(null)` | `None`
`Optional(Nullable null)` | `None`
`Optional(Nullable x)` | `Some(x)`

As well as the protection of the internal value of `Option`, there's protection for the return value
of the `Some` and `None` handler functions. You can't return `null` from those either; an exception will
be thrown.

```C#
// This will throw a ResultIsNullException exception
string res = GetValue(true)
.Some(x => (string)null)
.None((string)null);
```

`null` goes away if you use `Option`.

However, there are times when you may want your `Some` and `None` handlers to return `null`. This is mostly
when you need to use something in the BCL or from a third-party library, so momentarily you need to step
out of your warm and cosy protected optional bubble, but you've got an `Option` that will throw an
exception if you try.

So you can use `matchUnsafe` and `ifNoneUnsafe`:

```C#
string x = matchUnsafe( optional,
Some: v => v,
None: () => null );

string x = ifNoneUnsafe( optional, (string)null );
string x = ifNoneUnsafe( optional, () => GetNull() );
```
And fluent versions:
```C#
string x = optional.MatchUnsafe(
Some: v => v,
None: () => null
);
string x = optional.IfNoneUnsafe((string)null);
string x = optional.IfNoneUnsafe(() => GetNull());
```
That is consistent throughout the library. Anything that could return `null` has the `Unsafe` suffix. That
means that in those unavoidable circumstances where you need a `null`, it gives you and any other programmers
working with your code the clearest possible sign that they should treat the result with care.

### Option monad - gasp! Not the M word!

I know, it's that damn monad word again. They're actually not scary at all, and damn useful. But if you
couldn't care less (or _could_ care less, for my American friends), it won't stop you taking advantage of the
`Option` type. However, `Option` type also implements `Select` and `SelectMany` and is therefore monadic, which also means it can be used in LINQ expressions and much more!

```C#
Option two = Some(2);
Option four = Some(4);
Option six = Some(6);
Option none = None;

// This expression succeeds because all items to the right of 'in' are Some of int
// and therefore it lands in the Some lambda.
int r = match( from x in two
from y in four
from z in six
select x + y + z,
Some: v => v * 2,
None: () => 0 ); // r == 24

// This expression bails out once it gets to the None, and therefore doesn't calculate x+y+z
// and lands in the None lambda
int r = match( from x in two
from y in four
from _ in none
from z in six
select x + y + z,
Some: v => v * 2,
None: () => 0 ); // r == 0
```
This can be great for avoiding the use of `if then else`, because the computation continues as long as the
result is `Some` and bails otherwise. It is also great for building blocks of computation that you can compose
and reuse. Yes, actually compose and reuse, not like OOP where the promise of composability and modularity are
essentially lies.

To take this much further, all of the monads in this library implement a standard "functional set" of functions:
```C#
Sum // For Option it's the wrapped value.
Count // For Option is always 1 for Some and 0 for None.
Bind // Part of the definition of anything monadic - SelectMany in LINQ
Exists // Any in LINQ - true if any element fits a predicate
Filter // Where in LINQ
Fold // Aggregate in LINQ
ForAll // All in LINQ - true if all element(s) fits a predicate
Iter // Passes the wrapped value(s) to an Action delegate
Map // Part of the definition of any 'functor'. Select in LINQ
Lift / LiftUnsafe // Different meaning to Haskell, this returns the wrapped value. Dangerous, should be used sparingly.
Select
SelectMany
Where
```
This makes them into what would be known in Haskell as a Type Class (although more of a catch-all type-class than a set of well-defined type-classes).

* [Option and alternative-value-monads reference](https://louthy.github.io/language-ext/LanguageExt.Core/Monads/Alternative%20Value%20Monads/index.html)

__Monad transformer extensions__

> For this section you will need the `LanguageExt.Transformers` nu-get package

Monad transformers extensions allow for behaviours that work with nested monadic types. Imagine functionality for working with `Seq>` or a `Option>`, etc. without having to unpack the values bound within.

One problem with C# is it can't do higher order polymorphism (imagine saying `M where M : Monad` where the `M` is polymorphic like the `T`, and can be constrianed). There is a kind of cheat way to do it in C# through extension methods, but it still doesn't get you something that fits the pattern `M where M : Monad`. So there are limitations in that you can't write generic functions over higher-kinds, but with a bit of cunning we can generate code to deal with every pairing of monadic types.

> There's discussion later in the section on Ad-hoc Polymorphism of a more general approach, but it's a little too complicated use

As an example, below is a list of optional integers: `Lst>` (see lists later). We want to double all of the `Some` values, leave the
`None` alone and keep everything in the list:

```C#
using LanguageExt;
using static LanguageExt.Prelude;

var list = List(Some(1), None, Some(2), None, Some(3));

list = list.MapT(x => x * 2);
```
Notice the use of `MapT` instead of `Map`. If we used `Map` (equivalent to `Select` in `LINQ`), it would look like this:
```C#
var list = List(Some(1), None, Some(2), None, Some(3));

list = list.Map(x => x.Map( v => v * 2));
```
As you can see, the intention is much clearer in the first example, which is the point of functional programming most of the time. It's about declaring intent rather than the mechanics of delivery.

To make this work we need extension methods for `List>` that define `MapT` and `SumT` [for the one example above]. We also need one for
every pair of monads in this library (for one level of nesting `A>`), and for every function from the "standard functional set" listed above. That's 32 monads * 32 monads * 20 functions. That's a lot of extension methods (20,480!). Because of this, there's T4 template that generates 'monad transformers' that allows for nested monads.