Null handling

When the underlying primitive is a reference type, such as string, null is never a valid value. How it is treated depends on the method you use to create or parse an instance.

Instantiation

Passing null to From(...) throws ArgumentNullException:

var username = Username.From(null!); // throws ArgumentNullException

TryFrom(...) will not throw on null and instead will return false:

Username.TryFrom(null!, out var username); // returns false

Parsing

Parsing follows the same rules. Parse(...) parses the input into the primitive and then validates it, so a null input throws ArgumentNullException:

var username = Username.Parse(null!); // throws ArgumentNullException

TryParse(...) will not throw on null and instead will return false:

Username.TryParse(null, out var username); // returns false

Comparison operators

When a strong type is a reference type, the instance itself can be null. The ordering operators (<, <=, >, >=) require both operands to be non-null and throw ArgumentNullException otherwise:

Username? name = null;
name < Username.From("bob"); // throws ArgumentNullException

The equality operators (== and !=) treat null as a normal value and never throw:

Username? name = null;
name == Username.From("bob"); // false

Null propagation

Sometimes you might want to treat null as "no value" instead of invalid input and propagate it through. In such a case, you need to use FromNullable(...) instead of From(...):

Username? username = Username.FromNullable(null); // returns null

TryFromNullable(...) does the same for the Try pattern:

Username.TryFromNullable(null, out var username); // returns true, username is null