ntwilson/SafetyFirstv5.1.0

Let's look at an example. Seq.maxBy is a partial function because it's only defined for sequences that aren't empty. It will throw for an empty list. So let's consider the following unsafe code:

If an empty seq is passed in, it would throw the quite unhelpful:

Not to mention that the developer writing (or reading) this function may not even be aware that there's a problem that would need to be caught.

One way to make this total would be to adjust the output to reflect the possibility of an error:

By convention, this library uses an apostrophe after a function name for a function that returns a Result<_,_>. We try to make the name match any existing functions that would otherwise throw. (We also provide the equivalent functions with the Safe suffix instead of an apostrophe, e.g., Seq.maxBySafe. This is the only function available for use from C#, where apostrophes are not allowed in function names).

Of course the normal approach when calling the vip function would be to branch on the output and provide an execution path for what to do with an Error (in this case from an empty seq). But it may be that your application just doesn't allow for an empty seq of sales reps at all. This is a case where getting back to Exceptions is helpful, since we don't want to handle the possibility of an empty seq, we want to just crash and inform the user or developer that you need to provide at least one sales rep. In fact, if we can't handle the problem, and the only thing to do is crash the application or subsystem, the preferred approach is to switch to an Exception instead of propagating Result<_,_>s all the way up.

This library adds a few helper functions to make it easy to work with the Result type and the Option type. For both types, the unless function lets you "extract" the value assuming everything worked, provided a message that explains the problem. Here we could do

This has a higher development cost than using the partial maxBy function or First method, but if the exception is thrown, it provides a better error message because we now know a lot more about the context of the problem than we would from inside the maxBy function. We know that specifically our seq of SalesReps is empty, and can reflect that in the error message. Also this provides a lot more information to the reader of the vip function because it's obvious what the assumptions this function makes are (in this case, that the input includes at least one sales rep).

Since the Result type already contains error information in it, the Result type also has an expect function that functions just like unless but doesn't require an additional message. So you could do:

which has almost no cost compared to the partial maxBy function, but informs the programmer (and the reader) that maxBy could error, and that we're just assuming that it will work. If an Exception does occur though, this will end up throwing an equally unhelpful exception as maxBy.

But if we really don't allow for an empty set of sales reps, then maybe we want to explore the other option for making this function total: restricting the inputs to only valid inputs. Here, we could use the NonEmpty type to restrict the input to only allow a non-empty set of sales reps:

Seq.NonEmpty.maxBy doesn't ever throw an exception, because you can't create a NonEmptySeq unless you have at least one element. NonEmpty has a pattern matcher to create types like NonEmptySeq:

(or even)

Now we have one failure spot for an empty set of sales reps that occurs just where it's read in from the database, and from then on, the compiler keeps track of the fact that it isn't empty. This is analogous to checking for null when first loading the data, instead of including null checks in every function (now possible in C# too with the new nullable reference types).

Monadic error handling

F# types

This library adds computation expressions for Option<_> and Result<_,_> types. For example:

(note that for Result<_,_> expressions, the Error type must be the same for all results used in the expression).

If you're using F#5 or greater, you can take advantage of "Applicative Computation Expressions" which adds and! bindings inside a result expression. When using and! bindings, any errors will be aggregated together (using F#+'s semigroup append). For example,

C# types

This library adds the Result<_,_> type for C#, and even includes LINQ extensions so that the Result type can be used from a LINQ expression. When using LINQ, you can think of a Result a bit like a collection of length 1 if it contains an "Ok" value, or like a collection of length 0 if it contains an "Error" value. It's easiest to understand by seeing it in action:

(note that for Result<_,_> expressions, the Error type must be the same for all results used in the expression). You may also want to take a look at the Option<_> type introduced by LanguageExt which is similar to the Result<_,_> type, but doesn't carry with it any error information.

F# Functions

Below is the set of partial F# functions in FSharp.Core that this library provides total versions of by returning a Result<_,_> instead of throwing.

• Seq/List/Array.average
• Seq/List/Array.averageBy
• Seq/List/Array.chunkBySize
• Seq/List/Array.exactlyOne
• Seq/List/Array.find
• Seq/List/Array.findBack
• Seq/List/Array.findIndex
• Seq/List/Array.findIndexBack
• Seq/List/Array.head
• Seq/List/Array.item
• Seq/List/Array.last
• Seq/List/Array.max
• Seq/List/Array.maxBy
• Seq/List/Array.min
• Seq/List/Array.minBy
• Seq/List/Array.pick
• Seq/List/Array.reduce
• Seq/List/Array.reduceBack
• Seq/List/Array.skip
• Seq/List/Array.splitInto
• Seq/List/Array.tail
• Seq/List/Array.take
• Seq/List/Array.windowed
• List/Array.fold2
• List/Array.foldBack2
• List/Array.forall2
• List/Array.iter2
• List/Array.iteri2
• List/Array.map2
• List/Array.mapi2
• List/Array.map3
• List/Array.splitAt
• List/Array.zip
• List/Array.zip3
• Array.sub
• Map.ofSeq
• Map.ofList
• Map.ofArray

LINQ Functions

Below is the set of C# LINQ partial functions that this library provides total versions of by returning a Result<_,_> instead of throwing.

• Aggregate
• Average
• ElementAt
• First
• Last
• Max
• Min
• Single
• Zip

NOTE:

This library doesn't bother with altering error handling for any IO (working with files, database, network, etc.) for a few reasons.

1. For IO it is always obvious that an error is possible, and making that clear to the programmer/reader/debugger isn't helpful. Program logic that throws is often much less obvious.

2. The scope of all available IO functions that could throw is beyond what this library is intending to accomplish.

3. Composing Results with different possible errors is still very cumbersome compared to Exceptions. IO code will typically involve many calls with many different possible errors.

4. IO code is necessarily imperative rather than functional. Exceptions have proven themselves as the optimal solution for imperative code.

Restricted Types

These are types that this library creates to have a restricted set of possible values than it's parent type. We've already explored the NonEmpty set of collections briefly, which restricts a collection type to only allow values that contain at least one value. This library provides several, but the technique is fairly straightforward, so you are also encouraged to create your own when necessary. The Numbers module (described below) is a good example if you want to create similar types in your own codebase.

Collections

FiniteSeq

This one is unique in that there is no runtime check we can do to verify that a sequence is finite, so it's entirely based on developer assertions that the seq is finite. Marking a sequence finite is an important distinction since some functions can be safely called on any infinite list, but would be partial for finite lists (like take or skip or indexing). Conversely there are some functions that can be safely called on any finite list, but would diverge for infinite lists (like fold and everything that derives from fold like max/min, last, reduce, sum, length, exists, forall, etc.) (interestingly, forall and exists can return in some circumstances from an infinite list, but forall can never produce the value true, only false, and exists can never produce the value false, only true, so applying them to an infinite list is senseless).

Finite sequences are particularly important, since they can have value equality (two finite sequences that contain the same values are equal) instead of referential equality like seq (two sequences are only equal if they point to the same memory address). (seq cannot have value equality because comparing equality of infinite seqs could diverge).

There are three main sequence types in F#: Array, List, and seq. There are similarly three main sequence types in C#: Array, List, and IEnumerable (where, somewhat confusingly, when I say "List" from F# and C#, I'm talking about different types, but when I say "seq" and "IEnumerable", I'm talking about the same type). Working with F# Lists makes any interop with C# intolerable. Arrays are mutable, eager, and certain operations (like tail or cons) perform poorly. C# lists are similarly mutable and eager, and make F# interop difficult. Of course, we can choose whichever is best suited for our use upon creation, and then use seq/IEnumerable everywhere else, but this provides many challenges because of the fact that our seq could be infinite. The worst is the reference equality instead of structural equality mentioned above (this also means if you include a seq in any records or union types, those types lose their structural equality as well). This library introduces the FiniteSeq type for a lazily evaluated sequence that is constrained to be finite. It has structural equality, and can be constructed from any other sequence in O(1) time, just like a seq/IEnumerable. Even from C#, two FiniteSeq instances will be equal if they contain the same elements. The functions in the FiniteSeq module are safe for use with any FiniteSeq. It's built on top of the LazyList type provided by the FSharpx.Collections package. Note that from C#, this is one of the more convenient ways of caching an IEnumerable but keeping it lazy. You can use the .Finite() extension method to make any IEnumerable into a FiniteSeq.

The FiniteSeq type also uses the alias fseq and the FiniteSeq module also uses the alias FSeq

For example:

InfiniteSeq

To go along with FiniteSeq, it's helpful to have a type for representing a sequence that's known to be infinite. Some functions are excluded from the InfiniteSeq module (like fold), while others are known to be safe for use (like head). An InfiniteSeq can be created with the InfiniteSeq.init function (which behaves exactly like Seq.initInfinite), and the functions in the InfiniteSeq module are safe to use for infinite sequences (well, as safe as you can be. You can certainly construct a sequence that will hang forever as soon as you try to do anything useful with it, e.g., the sequence:

InfiniteSeq.init (fun _ -> 0) |> InfiniteSeq.filter ((<>) 0) will hang if you were to use any eager calculations with it, like take or head or find).

Note that from C#, you can use the InfiniteSeq module directly, but InfiniteSeq doesn't add much benefit if you're using LINQ style syntax. Since InfiniteSeq is an IEnumerable, you'll still see all of the regular LINQ extension methods, which will include all of the methods that should never be called on an infinite sequence.

NonEmpty

We've already been introduced to the NonEmpty type. It's actually a wrapper for any type of sequence, but the necessary type signature is a bit ugly (e.g., NonEmpty<seq<int>, int>) which is needed to satisfy .NET's type system, so there are aliases for many common types: NonEmptySeq<'a>, NonEmptyArray<'a>, NonEmptyFSeq<'a>, and NonEmptyList<'a> (that's an F# list). Feel free to use it with any other type of collection however. We also add modules Seq.NonEmpty, Array.NonEmpty, FSeq.NonEmpty, and List.NonEmpty for functions that take in a NonEmpty and have their signatures modified to reflect that. (There's also InfiniteSeq.asNonEmpty which returns a NonEmpty<InfiniteSeq<'a>, 'a> in case you need to pass an infinite seq to a function taking a NonEmpty). There are two ways to get a NonEmpty. One is a pattern matcher with any seq:

The other is to construct it with a head and tail

Number Types

Several functions rely on an integer being >= 0 or > 0. This library defines types for these numbers. A NaturalInt is an int constrained to be >= 0. A PositiveInt is constrained to be > 0. A NegativeInt is constrained to be < 0. Several functions will offer one version that will return a Result<_,_> if given a negative input, and another version that only accepts either a PositiveInt or NaturalInt (depending on the function's needs). You can create these types in a variety of ways.

1. pattern matching:

2. the verify functions:

(keep in mind that can be used with the Option.unless function):

3. the assume functions:

The assume functions are partial, but are helpful for cases where the int so obviously satisfies the constraint that using pattern matching or an unless function would be laughable:

Functions that utilize PositiveInt include chunksOf (a safe version of chunkBySize), splitIntoN (a safe version of splitInto), and window (a safe version of windowed). Functions that utilize NaturalInt include drop and skip.