v4.0_UpgradeGuide.md

A number of breaking changes were introduced in v. 4. This guide will help you understand these changes and how to update your codebase to work with the latest version of SafetyFirst.

InfiniteSeq rework

A lot of thought has gone into infinite sequences in v. 4. The InfiniteSeq type now reflects a sequence that is conceptually infinite, but in reality still finite. Anytime an InfiniteSeq is created, you must now provide an upper-bound that reflects the number of elements where, if that many elements is produced, you can be sure that the computation has "hung" and you need to abort. It's recommended that this be several orders of magnitude higher than the largest number of elements you can imagine being feasible. Any computation that could potentially cause a hang will now either evaluate eagerly and return a Result<'a, InfiniteSeqHung>, or evaluate lazily and return a seq<Result<'a, InfiniteSeqHung>. With these changes, using infinite sequences is safe from actually hanging, and you have an opportunity to recover from any potential hangs.

Functions restored to the Seq module

This isn't a breaking change, but large enough to be worth noting here. Several functions were been removed from the Seq module in v 3, as they diverge for infinite sequences. This proved to be too onerous to work with (especially in conjunction with SafetyFirst.Strict), and in some cases would negatively impact performance. In v 4, these functions were restored, and the warnings turned off in SafetyFirst.Strict. This is in-part from the revamp to the InfiniteSeq type & module, and it is now expected that any seq known to be infinite should be made into an InfiniteSeq. The functions that were restored include:

average averageBy findBack findIndexBack last max maxBy min minBy reduce reduceBack splitInto

Similarly, several functions have been restored to the Seq.NonEmpty module for the same reason. These include:

average max maxBy min minBy reduce length fold rev

_.NonEmpty.groupBy and a couple other functions changed signature

Where a function in a NonEmpty module is known to return a non-empty output, it is updated to return a NonEmpty collection. Where this upgrade causes a problem, you may simply call, e.g., List.NonEmpty.toList or Array.NonEmpty.toArray.