In this article, you will get an overview of nulls and generics with IComparable, just so you can love the new C# again.
Introduction
The new nullable context can be enabled via the <Project><PropertyGroup><Nullable>enable</Nullable> element in your C# project (.csproj) file. It gives you full null-state static analysis at compile-time and promises to eliminate every single NullReferenceException once and for all. Previously, we talked about the most fundamental null, type and reference checks (How to Start a Robust C# Project in the New Nullable Context with Generics?). Today, we want to cover something slightly more challenging, namely, range checks or "index" checks. Code quality is of paramount importance and deserves your second look. This article aims to provide an overview of nulls and generics with IComparable<T>, just so you can love the new C# again. Little things matter.
Using the Code
To start, let's begin with a simple method for illustration, which we call IsAbout to emphasize that an Equals comparison is intended to be inexact, such as +0.0 == -0.0, or its default implementation is usually more than good enough:
using System;
using System.Diagnostics.CodeAnalysis;
namespace Pyramid.Kernel.Up
{
partial class It
{
public static bool IsAbout<J>(this J it, J that) where J : IComparable<J>? =>
it.Is(out var o) ? that.Is(out var p) && o.CompareTo(p) == 0 : that.Isnt();
}
}
Data often come from external sources, where nulls may be the norm, especially in relational databases, which in fact was the primary motivation for Nullable<T>. To declare the acceptance of nulls in a generic method, we can write either IsAbout<J>(this J it, J that) where J : IComparable<J>? or IsAbout<J>(this J? it, J? that) where J : IComparable<J>. For the sake of brevity and consistency, we want to embed all nullability information in types rather than in parameters, fields or properties. Write once and for all. If you write twice or many times, chances are you'll introduce inconsistencies everywhere in your code. Code consistency matters, therefore the first form is preferred. The implementation above looks cryptic, but it demonstrates how short code can be after a simple logical reduction, which will definitely get inlined by JIT. If you prefer human readability, the equivalent implementation is given below:
namespace Pyramid.Kernel.Up
{
partial class It
{
public static bool IsAbout<J>(this J it, J that) where J : IComparable<J>?
{
if(it.Is(out var o))
{
if (that.Is(out var p)) return o.CompareTo(p) == 0;
else return false;
}
else
{
if (that.Is()) return false;
else return true;
}
}
}
}
The core principle of robust code is to list all permutations, the same thing we do in multi-threading, just to ensure that we have not missed any single possible scenario. It's not difficult at all, but it's tremendously tedious, prone to error. That's why we bother to wrap even the simplest code into a C# extension method, which will end up inlined by JIT without any run-time overhead or performance penalty, much like a C++ macro. This way, if we by chance make a careless mistake, we can correct it once and for all as a global code policy. One place to fix them all, isn't that cool? Unfortunately, the above method doesn't work for Nullable<T>. We must overload it with a separate, dedicated version:
namespace Pyramid.Kernel.Up
{
partial class It
{
public static bool IsAbout<J>(this J? it, J? that) where J : struct, IComparable<J> =>
it.Is() ? that.Is() && it.Be().IsAbout(that.Be()) : that.Isnt();
}
}
The new C# comes with a new documentation element called <inheritdoc>, which comes in handy if you're overloading or overriding lots of methods. It works even with classes and interfaces, where classes may choose to inherit interface documentation. The cref attribute appears in many documentation elements, such as <see> and <seealso>, but has been way underdocumented by Microsoft. It actually can refer to any code member, including operators and custom casts, implicit or explicit, all integrated into Visual Studio with every single mouse hover and tooltip. We will not cover everything here. Instead, they will come complete gradually in our future code samples. To support all scenarios, we have IsAbove and IsBelow defined as follows:
namespace Pyramid.Kernel.Up
{
partial class It
{
public static bool IsAbove<J>(this J it, J that) where J : IComparable<J>? =>
it.Is(out var o) && (!that.Is(out var p) || o.CompareTo(p) > 0);
public static bool IsAbove<J>(this J? it, J? that) where J : struct, IComparable<J> =>
it.Is() && (!that.Is() || it.Be().IsAbove(that.Be()));
public static bool IsBelow<J>(this J it, J that) where J : IComparable<J>? =>
it.Is(out var o) ? that.Is(out var p) && o.CompareTo(p) < 0 : that.Is();
public static bool IsBelow<J>(this J? it, J? that) where J : struct, IComparable<J> =>
it.Is() ? that.Is() && it.Be().IsBelow(that.Be()) : that.Is();
}
}
How about IsAboutOrAbove, IsAboutOrBelow and IsNotAbout? Well, it works better with !IsBelow, !IsAbove and !IsAbout, because C# generics with value types results in code bloat as in C++. Whenever possible, we aim to keep the minimal primitives only, observing C++ minimalism religiously. So, why define Isnt in my previous article? Well, it's simple. Why define == null and != null as two separate primitives? They are used often enough to deserve their own CLR instructions. Besides, our Isnt overloads work with reference types mostly, which with C# generics reuse the same code unlike C++, no code bloat there. That being said, the newer CPU instruction sets come with dedicated operations to match ==, !=, <, <=, > and >=, all six of them, which we definitely want to leverage. Well, let's go with IsntBelow, IsntAbove and IsntAbout for symmetric completeness anyway, hardware first:
namespace Pyramid.Kernel.Up
{
partial class It
{
public static bool IsntAbout<J>(this J it, J that) where J : IComparable<J>? =>
it.Is(out var o) ? that.Isnt(out var p) || o.CompareTo(p) != 0 : that.Is();
public static bool IsntAbout<J>(this J? it, J? that) where J : struct, IComparable<J> =>
it.Is() ? that.Isnt() || it.Be().IsntAbout(that.Be()) : that.Is();
public static bool IsntAbove<J>(this J it, J that) where J : IComparable<J>? =>
it.Isnt(out var o) || that.Is(out var p) && o.CompareTo(p) <= 0;
public static bool IsntAbove<J>(this J? it, J? that) where J : struct, IComparable<J> =>
it.Isnt() || that.Is() && it.Be().IsntAbove(that.Be());
public static bool IsntBelow<J>(this J it, J that) where J : IComparable<J>? =>
it.Is(out var o) ? that.Isnt(out var p) || o.CompareTo(p) >= 0 : that.Isnt();
public static bool IsntBelow<J>(this J? it, J? that) where J : struct, IComparable<J> =>
it.Is() ? that.Isnt() || it.Be().IsntBelow(that.Be()) : that.Isnt();
}
}
Given the Is method group, we want to define their Be equivalent:
namespace Pyramid.Kernel.Up
{
partial class It
{
public static J BeAbout<J>(this J it, J that) where J : IComparable<J>? =>
it.IsAbout(that) ? it : throw new OverflowException();
public static J? BeAbout<J>(this J? it, J? that) where J : struct, IComparable<J> =>
it.IsAbout(that) ? it : throw new OverflowException();
public static J BeAbove<J>(this J it, J that) where J : IComparable<J>? =>
it.IsAbove(that) ? it : throw new OverflowException();
public static J? BeAbove<J>(this J? it, J? that) where J : struct, IComparable<J> =>
it.IsAbove(that) ? it : throw new OverflowException();
public static J BeBelow<J>(this J it, J that) where J : IComparable<J>? =>
it.IsBelow(that) ? it : throw new OverflowException();
public static J? BeBelow<J>(this J? it, J? that) where J : struct, IComparable<J> =>
it.IsBelow(that) ? it : throw new OverflowException();
}
}
There are two things to note here: the choice of OverflowException over IndexOutOfRangeException and the decision to skip a custom message. Firstly, range checks are often performed for index checks, which are built into C# and .NET, so we don't want to check them twice. If we do actually check ranges, chances are we are checking against an overflow, in either arithmetics or conversions, hence an OverflowException. Secondly, why skip a custom message? Well, it's my style, because I don't want to translate custom messages into hundreds of local languages, a requirement by the standard implementation of exceptions. Microsoft has supplied the translations for all default exception messages. Why not leverage them? Now, we want to check ranges in one call, where the absence of either boundary skips its corresponding check for semantic naturalness:
namespace Pyramid.Kernel.Up
{
partial class It
{
public static J BeWithin<J>(this J it, J min, J max) where J : IComparable<J>? =>
it.IsWithin(min, max) ? it : throw new OverflowException();
public static J? BeWithin<J>(this J? it, J? min, J? max) where J : struct, IComparable<J> =>
it.IsWithin(min, max) ? it : throw new OverflowException();
public static bool IsWithin<J>(this J it, J min, J max) where J : IComparable<J>? =>
it.Is(out var o) ?
(min.Isnt(out var p) || o.CompareTo(p) >= 0) &&
(max.Isnt(out var q) || o.CompareTo(q) <= 0) :
min.Isnt();
public static bool IsWithin<J>(this J? it, J? min, J? max)
where J : struct, IComparable<J> =>
it.Is() ?
(min.Isnt() || it.Be().IsntBelow(min.Be())) &&
(max.Isnt() || it.Be().IsntAbove(max.Be())) :
min.Isnt();
public static bool IsntWithin<J>(this J it, J min, J max) where J : IComparable<J>? =>
it.Is(out var o) ?
min.Is(out var p) && o.CompareTo(p) < 0 || max.Is(out var q) && o.CompareTo(q) > 0 :
min.Is();
public static bool IsntWithin<J>(this J? it, J? min, J? max)
where J : struct, IComparable<J> =>
it.Is() ?
min.Is() && it.Be().IsBelow(min.Be()) || max.Is() && it.Be().IsAbove(max.Be()) :
min.Is();
}
}
The code gets pretty big now. You might wonder why not ease the burden of null checks by delegating part of that responsibility to CompareTo, which accepts a null anyway. Well, that's only for the right-hand side, isn't it? How about the left-hand side? If you write it?.CompareTo(that), you end up with an int?, which actually complicates the story. Plus, the correct and fast implementation of CompareTo is usually fairly sophisticated beside those standard primitive types, which seldom gets inlined. By performing null checks outside CompareTo, we at least inline all our null checks, as we should. To ensure inlining, if that matters to you so much, you can use the new MethodImplOptions.AggressiveInlining option, available after .NET 4.5 or .NET Core 1.0. An even more aggressive option called MethodImplOptions.AggressiveOptimization was introduced after .NET 5 or .NET Core 3.0. You might want to have a look and take advantage. To verify that your method is indeed inlined, you can leverage a Reflection method called MethodBase.GetCurrentMethod. If it doesn't return your method, it means your method doesn't exist, therefore inlined. Congratulations!
using System.Reflection;
using System.Runtime.CompilerServices;
namespace Pyramid.Kernel.Up
{
partial class It
{
static MethodBase? _method;
[MethodImpl(MethodImplOptions.AggressiveInlining)]
public static bool IsWithin<J>(this J it, J min, J max) where J : IComparable<J>?
{
_method = MethodBase.GetCurrentMethod();
return
it.Is(out var o) ?
(min.Isnt(out var p) || o.CompareTo(p) >= 0) &&
(max.Isnt(out var q) || o.CompareTo(q) <= 0) :
min.Isnt();
}
}
}
If you are curious about how JIT decides what and what not to inline, the most complete explanation I can find online is an old, archived blog post by Vance Morrison (To Inline or not to Inline: That is the question), who worked on JIT optimization at Microsoft. If that doesn't satisfy your hunger for knowledge, the best article about .NET performance is the official publication by Microsoft, now archived as well (Writing Faster Managed Code: Know What Things Cost), written by Jan Gray. If you Google these two names, you'll find out a lot more .NET performance resources, mostly in the form of semi-official blogs at Microsoft. Furthermore, if you Google hard enough, you may come across this question at Stack Overflow (Is there an updated version of "Writing Faster Managed Code: Know What Things Cost"?), where Jan explained why they had very rarely blogged about .NET performance. In fact, they encourage you to do your own microbenchmarks, if you know where you want to deploy your code, such as these two posts (CLR Inside Out: Measure Early and Often for Performance, Part 1 and CLR Inside Out: Measure Early and Often for Performance, Part 2). There's no shortcut. You must learn on your own.
If you prefer human readability, an equivalent implementation is given below:
namespace Pyramid.Kernel.Up
{
partial class It
{
public static bool IsWithin<J>(this J it, J min, J max) where J : IComparable<J>? =>
{
if (it.Is(out var o))
{
if (min.Is(out var p))
{
if (max.Is(out var q)) return o.CompareTo(p) >= 0 && o.CompareTo(q) <= 0;
else return o.CompareTo(p) >= 0;
}
else
{
if (max.Is(out var q)) return o.CompareTo(q) <= 0;
else return true;
}
}
else
{
if (min.Is())
{
if (max.Is()) return false;
else return false;
}
else
{
if (max.Is()) return true;
else return true;
}
}
}
}
}
You see, robustness is tedious. That's why we don't want to write it from scratch every time. We want C# type-safe macros, such as extension methods and value types, to help reusing and managing robust code without any run-time overhead. Next time, we'll dive into the bits and make our own Id value type, a special Guid that addresses cloud objects, something a little more exciting.
Points of Interest
- The core principle of robust code is to list all permutations, the same thing we do in multi-threading, just to ensure that we have not missed any single possible scenario. Brute-force logic always works, however clumsy or boring it looks.
- The new C# comes with a new
<inheritdoc> element to inherit documentation, where its cref attribute has been way underdocumented. In fact, it can refer to anything, including operator overloads and custom casts, implicit or explicit, all seamlessly integrated into Visual Studio with every mouse hover and tooltip. - The new .NET introduces two options to
MethodImplOptions, AggressiveInlining available after .NET 4.5 or .NET Core 1.0 and AggressiveOptimization, available after .NET 5 or .NET Core 3.0, both great additions to your arsenal in writing faster code.
History
- 2nd July, 2021: Initial version
Montreal is the second largest French city in the world, next to Paris. I like the fact that real estate is dirt cheap here, so cheap that software development alone enables a financial capacity to afford a nearly 2,000-square-foot luxurious condo right in the middle of Downtown Montreal, a 5-minute walk from my office, beside the largest and oldest art museum in Canada with visitors and tourists from all over the planet, including Hollywood stars. I've chosen C# as my first language at Code Project, because it is the only garbage-collected language and platform meeting the performance requirements for real-time game programming, proven by Unity. Code must be perfect, providing safety, security, performance, scalability, availability, reliability, maintainability, extensibility, portability, compatibility, interoperability, readability, productivity, just to name a few. C# is the only language that comes close, with Rust second to it. That being said, even C# is far from being perfect. I dream my own programming language, while on my journey to it. We will see how it goes!
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
)