akamsteeg / pitcher

Pitcher is a small helper library to easily throw exceptions and reduce code size by moving the tedious if..throw stuff out of your code.

Pitcher

Pitcher is a utility library to simplify throwing exceptions, especially when checking arguments. It makes methods easier to inline, by reducing code size.

Platform support

.NET Framework	.NET Core
✔️	✔️

Installation

The Pitcher NuGet package is the prefered way to install and use it.

install-package Pitcher

Usage

To use Pitcher, add a using to your source file:

using Pitcher;

Then, you can use Throw or Throw<T> to throw exceptions.

Throw

Throw an exception directly:

Throw.This(new ArgumentNullException(nameof(args));

Throw an exception based on a condition:

Throw.When(args == null, new ArgumentNullException(nameof(args)); // This will always allocate the exception

Throw an exception based on a condition, with a Func<T> to create the exception in a more complex way:

Throw.When(args == null, () => new ArgumentNullException(nameof(args));

ArgumentNullException

There are helpers for simplifying argument checking and throwing an ArgumentNullException.

// Throw ArgumentNullException for parameter
Throw.ArgumentNull.For(nameof(args));

// Throw ArgumentNullException for parameter, with message
Throw.ArgumentNull.For(nameof(args), "Args is a required parameter");

// Throw ArgumentNullException for parameter, when a condition is met
Throw.ArgumentNull.When(args == null, nameof(args));

// Throw ArgumentNullException for parameter with a message, when a condition is met
Throw.ArgumentNull.When(args == null, nameof(args), "Args is a required parameter");

// Throw ArgumentNullException for parameter, when the parameter is null
Throw.ArgumentNull.WhenNull(args, nameof(args));

// Throw ArgumentNullException for parameter with a message, when the parameter is null
Throw.ArgumentNull.WhenNull(args, nameof(args), "Args is a required parameter");

// Throw ArgumentNullException for a null or empty string
Throw.ArgumentNull.WhenNullOrEmpty(args, nameof(args));

// Throw ArgumentNullException with a message for a null or empty string
Throw.ArgumentNull.WhenNullOrEmpty(args, nameof(args), "Args is a required parameter");

// Throw ArgumentNullException for a null, empty or whitespace string
Throw.ArgumentNull.WhenNullOrWhitespace(args, nameof(args));

// Throw ArgumentNullException with a message for a null, empty or whitespace string
Throw.ArgumentNull.WhenNullOrWhitespace(args, nameof(args), "Args is a required parameter");

// Throw ArgumentNullException for a null or empty IEnumerable<T>
Throw.ArgumentNull.WhenNullOrEmpty(new List<string>(), nameof(args));

// Throw ArgumentNullException with a message for a null or empty IEnumerable<T>
Throw.ArgumentNull.WhenNullOrEmpty(new List<string>(), nameof(args), "Args is a required parameter");

ArgumentOutOfRangeException

Specific helpers are available for throwing an ArgumentOutOfRangeException.

// Throw ArgumentOutOfRangeException for parameter
Throw.ArgumentOutOfRange.For(nameof(args));

// Throw ArgumentOutOfRangeException for parameter, with message
Throw.ArgumentOutOfRange.For(nameof(args), "Args is out of the acceptable range");

// Throw ArgumentOutOfRangeException for parameter, when a condition is met
Throw.ArgumentOutOfRange.When(args < 0, nameof(args));

// Throw ArgumentOutOfRangeException for parameter with a message, when a condition is met
Throw.ArgumentOutOfRange.When(args < 0, nameof(args), "Args is out of the acceptable range");

Throw<T>

For exceptions without parameters or when you don't care about the parameters, you can use Throw<T>.

// Throw an exception
Throw<InvalidOperationException>.Now();

//Throw an exception based on a condition
Throw<InvalidOperationException>.When(obj == null);

License

Pitcher uses the MIT license, see the LICENSE file.

pitcher's Issues

Add Throw.ArgumentNull.WhenNullOrEmpty<T>(IEnumerable<T>, string, [string])

Currently, a user has to do the following to check a IEnumerable<T> parameter:

Throw.ArgumentNull.When(parameter == null || !parameter.Any(), nameof(parameter))

This defeats the purpose somewhat, since we have a big chunk of code there and it's easy to do wrong, e.g. by forgetting the null check.

Suggestion, add WhenNullOrEmpty<T>(IEnumerable<T>, string, [string]) methods to throw an ArgumentNullException when the specified IEnumerable<T> is null or empty.

Example:

// parameter is any IEnumerable<T>
Throw.ArgumentNull.WhenNullOrEmpty(parameter, nameof(parameter));
Throw.ArgumentNull.WhenNullOrEmpty(parameter, nameof(parameter), message: "Collection cannot be null or empty");

Move to a single .NET Standard 2.0 target

Currently, Pitcher multi-targets to .NET 4.0 and .NET Standard 1.0. These are both very old and not very likely to be used for the modern high-performance code Pitcher is intended to be used in.

Suggestion: Drop the .NET 4.0 target and move to .NET Standard 2.0 exclusively.

.NET Standard 2.0 is properly supported from .NET 4.7.2 onwards (if we forget the dumpster fire that's the tacked on support in 4.6.something). That means we support everything from april 2018 onwards. That's good enough I think And, moving to a single modern TFM should make future upgrades and additions easier too.

This is a breaking change, we need to increase the major version number for this.

Add SourceLink support

The whole symbols package stuff is replaced by SourceLink, so we should add/enable that too.

See akamsteeg/AtleX.CommandLineArguments#40 for more information on how to do this.

Move from SourceLink + embedded PDB to snupkg

Currently, we create a single NuGet package with SourceLink and an embedded PDB file. Microsoft updated the guidance for SourceLink to use a .snupkg for packages distributed using NuGet.org. This uses the NuGet.org symbol server to distribute the symbols.

To generate the package, we must add the following to the .csproj in the propertygroup with the target framework etc.:

<IncludeSymbols>true</IncludeSymbols>
<SymbolPackageFormat>snupkg</SymbolPackageFormat>

Note: We should also adapt the build and release pipelines in Azure DevOps to properly create and publish .snupkg files.

Add Throw.ArgumentOutOfRange.WhenLessThan<T>() where T = IComparable<T>

Add Throw.ArgumentNull.WhenNullOrWhitespace(string, string, [string])

(Related to #7)

Currently, to throw an ArgumentNullException for a string that's null or contains only whitespace a user has to do the following:

Throw.ArgumentNull.When(string.IsNullOrWhitespace(parameter), nameof(parameter));

That defeats the purpose a bit since Pitcher aims to reduce code sizes.

Suggestion: Add Throw.ArgumentNull.WhenNullOrWhitespace(string, string, [string]) methods

Example:

string s = null; // or s = "   ";
Throw.ArgumentNull.WhenNullOrWhitespace(obj: s, parameterName: nameof(s));
Throw.ArgumentNull.WhenNullOrWhitespace(obj: s, parameterName: nameof(s), message: "String cannot be null or only whitespace");

Add Throw.ArgumentOutOfRange.WhenMoreThan<T>() where T = IComparable<T>

Remove the ReportGenerator tool from the azure-pipelines yaml and replace it with the built-in Cobertura support of Azure DevOps

Currently, the code coverage is measured with the awesome Coverlet library that exports a report in Cobertura format. In the azure-pipelines.yml file, we use the dotnet-reportgenerator-globaltool to create an HTML report and publish those to Azure DevOps.

In Sprint 150 of Azure DevOps native Cobertura support is added to Azure DevOps. We can remove the dotnet-reportgenerator-globaltool from our build pipeline and just publish the cobertura.xml file directly in the PublishCodeCoverageResults step. Azure DevOps will then generate a pretty report.

"is null" should be used instead of "== null"

When using == null, it's possible that the code is lying by overriding the Equals(obj) method and returning true when obj is null. Or even worse, when there's a bug in the overriden Equals(obj) that causes it to throw for example a NullReferenceException. We want Pitcher to throw an exception when something is null, not when something might possible in some cases sometimes maybe null.

Add Throw.ArgumentOutOfRange.WhenNegativeNumber()

Enable deterministic builds

Enable deterministic builds using the guidance from Claire Novotny: https://github.com/clairernovotny/DeterministicBuilds/

Replace Throw.ArgumentNull.WhenNull(string, string, [string]) with new Throw.ArgumentNull.WhenNullOrEmpty(string, string, [string])

Currently, there's an overload for Throw.ArgumentNull.WhenNull() that works on strings and does a string.IsNullOrEmpty() internally. That's confusing, because an empty string is not null but it still throws from a When_Null_() method.

Suggestion:

1. Deprecate and remove the current Throw.ArgumentNull.WhenNull(string, string, [string]) methods;
2. Add new Throw.ArgumentNull.WhenNullOrEmpty(string, string, [string]) methods.

Example

string s = null;

Throw.ArgumentNull.WhenNullOrEmpty(obj: s, parameterName: nameof(s));

Throw.ArgumentNull.WhenNullOrEmpty(obj: s, parameterName: nameof(s), message: "String cannot be null or empty");

Add Throw.ArgumentOutOfRange.WhenPositiveNumber()

Add overloads for Throw.ArgumentNull.WhenNull() for strings

Currently, Throw.ArgumentNull.WhenNull() works on objects. However, a lot of parameters you'd want to check are strings. So, no you have to do Throw.ArgumentNull.WhenNull(string.IsNullOrEmpty(parameter), nameof(parameter)) which is silly. We should add overloads to Throw.ArgumentNull.WhenNull() that work on strings directly and do the null-or-empty check themselves.

Add strong naming

Microsoft recommends strong-naming NuGet packages and v2.0.0 is the perfect opportunity to add it to this library.

Update benchmark config to the new BenchmarkDotNet configuration system

In 0.12.1, BenchmarkDotNet changed their configuration system. Right now Pitcher is using the old system which results in build warnings because the old system is obsolete. To avoid builds breaking when BenchmarkDotNet removes the obsolete old configuration system, we should update to the new one.