Succinct<T> v2 will introduce breaking changes to provide speed improvements and naming consistency

[DavidArno]

Introduction

v2.0.0 of Succinc will introduce a number of changes, some of which are breaking changes for anyone using v1.x. The changes fall into four distinct categories detailed below. Please take the time to read the notes below before upgrading so you can:

1. understand what might break,
2. plan the fixing process and
3. decide if you can be bothered to make the changes to gain the benefits v2 brings.

   Pattern matching

Risk of code breakages: very low Difficulty in fixing breakages: very hard

The entire pattern-matching code base has been rewritten. The previous 60 classes that handled pattern matching have been replaced with just 15 classes and around 40 new interfaces. This has two benefits: the code is easier to understand, and more importantly, it is now significantly faster than before. However, a significant number of those 60 classes were public, though most had internal constructors.

• If you have simply written pattern-matching expressions using these classes, you will not be affected.
• There was a design flaw in the original matchers for "normal" types (ie, not options, unions) that allowed expressions like x.Match.With(1).Do(...).To<string>().... In other words a .To could be introduced after using With or Where. The expressions before To were then unreachable. This design flaw has now been fixed, so if you've written code like this, it'll no longer compile.
• If you are doing anything "clever" with these classes, then your code will break horribly, as most have now gone and what's left has different names. If this applies to you, please create an issue here on Github explaining what you were doing and I'll try and assist you in reworking things to work with v2.

  The Succinct.PartialApplications namespace has moved to Succinct.Functional and the methods that used the ActionWithOptionalParameter delegates have been removed.

Risk of code breakages: high Difficulty in fixing breakages: very easy (for methods in new namespace)/ medium (for removed methods)

Most of the partial application support methods (the Compose and TailCompose method groups) have been moved to a new namespace. In addition, those TailCompose methods that used the ActionWithOptionalParameter delegates have been removed (as have the delegates themselves). The reason for this is that:

1. I've started introducing other functional helper methods and it made sense to group them all in the one namespace.
2. The new Action methods, (for typing action lambdas) remove the need for the ActionWithOptionalParameter delegates.

As of v2.0.0, the old methods still exist (except as stated above), they have simply been marked as obsolete, which will yield warnings for any code that uses these methods. The chances are though, that you are following the good practice of treating warnings as errors, so this will break your code.

The fix for methods that still exist is simple: replace any occurrence of using Succinct.PartialApplications with using Succinct.Functional.

The fix for the removed methods is to wrap the method being tail composed inside an Action() call to convert it to an action lambda.

Methods that return Option<T> have been renamed to TryXXX

Risk of code breakages: very high Difficulty in fixing breakages: easy Succinc provides extension methods to string that attempt to parse a value within that string and return an Option<T> of Some (with the parsed value) or None. The common convention in F# is to add a Try suffix to functions that return an option. I have therefore renamed the parse methods to TryXXX to follow this convention.

Likewise, Succinc provides extension methods to IEnumerable<> that offer alternatives to the XXXOrDefault methods. These were called XXXOrNone. As of v2.0.0, they too have being renamed to TryXXX.

The methods affected are:

BooleanParser

• ParseBoolean -> TryParseBoolean

EnumParser

• ParseEnum -> TryParseEnum

FloatParsers

• ParseFloat -> TryParseFloat
• ParseDouble -> TryParseDouble
• ParseDecimal -> TryParseDecimal

IntParsers

• ParseSignedByte -> TryParseSignedByte
• ParseUnsignedByte -> TryParseUnsignedByte
• ParseShort -> TryParseShort
• ParseUnsignedShort -> TryParseUnsignedShort
• ParseInt -> TryParseInt
• ParseUnsignedInt -> TryParseUnsignedInt
• ParseLong -> TryParseLong
• ParseUnsignedLong -> TryParseUnsignedLong

OptionExtensionsForIEnumerable

• FirstOrNone -> TryFirst
• LastOrNone -> TryLast
• SingleOrNone -> TrySingle
• ElementAtOrNone -> TryElementAt

Again, as of v2.0.0, the old methods still exist, they have simply been marked as obsolete, which will yield warnings for any code that uses these methods. Once more, because you are likely following the good practice of treating warnings as errors, these changes will break your code.

The fix is fairly simple: replace any occurrence of the old method name with the new one in the list above.

None.Value becomes None.none

Risk of code breakages: very low Difficulty in fixing breakages: easy

Since C# 6 introduced static imports, using None.Value becomes clunky. Therefore Value has been renamed to none, allowing a static import of None and the use of none directly.

Again, as of v2.0.0, the old property still exists and has been marked as obsolete, which will yield warnings for any code that uses None.Value. Once more, because you are likely following the good practice of treating warnings as errors, this change will break your code if you are using None.Value directly (which seems unlikely).

The fix is fairly simple: replace any occurrence of None.Value with a using static SuccincT.Unions.None; line and reference none directly.

[DavidArno]

v2.0.0 has been released. Closing this issue.