API Reference

Complete documentation for all Pragmatic.Ensure methods.

Null Checks

ThrowIfNull

Throws if a reference type or nullable value type is null.

Ensure.ThrowIfNull(user);              // Reference type
Ensure.ThrowIfNull(nullableInt);       // Nullable value type

Parameter	Type	Exception
value	T? where T : class	ArgumentNullException
value	T? where T : struct	ArgumentNullException

IsNotNull

Returns true if the value is not null. Supports null-state analysis via [NotNullWhen(true)].

if (Ensure.IsNotNull(user))
{
    // 'user' is known to be non-null here
    Console.WriteLine(user.Name);
}

String Checks

ThrowIfNullOrEmpty / ThrowIfNullOrWhiteSpace

Ensure.ThrowIfNullOrEmpty(name);       // Null or ""
Ensure.ThrowIfNullOrWhiteSpace(name);  // Null, "", or whitespace only

Method	Throws On
ThrowIfNullOrEmpty	null, ""
ThrowIfNullOrWhiteSpace	null, "", " "

Length Validation

Ensure.ThrowIfLongerThan(name, 100);           // Max length
Ensure.ThrowIfShorterThan(name, 2);            // Min length
Ensure.ThrowIfLengthOutOfRange(name, 2, 100);  // Both

Format Validation

Ensure.ThrowIfNotEmail(email);              // RFC 5322 email format
Ensure.ThrowIfNotUrl(url);                  // Valid URL (HTTP/HTTPS)
Ensure.ThrowIfNotUrl(url, httpsOnly: true); // HTTPS only
Ensure.ThrowIfNotPhone(phone);              // E.164 phone format
Ensure.ThrowIfNotCreditCard(card);          // Luhn algorithm
Ensure.ThrowIfNotMatch(value, @"^\d{5}$");  // Custom regex

Is* String Methods

Ensure.IsNotNullOrEmpty(value)      // true if not null/empty
Ensure.IsNotNullOrWhiteSpace(value) // true if not null/empty/whitespace
Ensure.IsLengthInRange(value, min, max)
Ensure.IsEmail(value)
Ensure.IsUrl(value)
Ensure.IsPhone(value)
Ensure.IsCreditCard(value)
Ensure.IsMatch(value, pattern)

Numeric Checks

All numeric methods use generic constraints for maximum flexibility.

Range Validation

Ensure.ThrowIfNegative(value);           // value < 0
Ensure.ThrowIfNegativeOrZero(value);     // value <= 0
Ensure.ThrowIfZero(value);               // value == 0
Ensure.ThrowIfPositive(value);           // value > 0
Ensure.ThrowIfOutOfRange(value, 0, 100); // value outside [0, 100]
Ensure.ThrowIfGreaterThan(value, max);   // value > max
Ensure.ThrowIfLessThan(value, min);      // value < min

Works with: int, long, decimal, double, float, and any INumber<T> type.

Is* Numeric Methods

Ensure.IsPositive(value)        // value > 0
Ensure.IsNegative(value)        // value < 0
Ensure.IsZero(value)            // value == 0
Ensure.IsNotZero(value)         // value != 0
Ensure.IsNotNegative(value)     // value >= 0
Ensure.IsInRange(value, min, max)
Ensure.IsAtLeastMin(value, min)
Ensure.IsAtMostMax(value, max)

Collection Checks

ThrowIfEmpty / ThrowIfNullOrEmpty

Ensure.ThrowIfEmpty(items);       // Null or no items
Ensure.ThrowIfNullOrEmpty(items); // Alias for ThrowIfEmpty

Optimized overloads for:

• IEnumerable<T> - Uses Any()
• ICollection<T> - Uses Count
• IReadOnlyCollection<T> - Uses Count
• IList<T> - Uses Count
• T[] - Uses Length

IsNotNullOrEmpty

if (Ensure.IsNotNullOrEmpty(items))
{
    foreach (var item in items)
    {
        // Safe to enumerate
    }
}

Guid Checks

Ensure.ThrowIfEmpty(id);    // Guid.Empty
Ensure.IsNotEmpty(id);      // true if not Guid.Empty

DateTime Checks

Ensure.ThrowIfDefault(date);     // default(DateTime)
Ensure.ThrowIfInPast(date);      // Before DateTime.Now
Ensure.ThrowIfInFuture(date);    // After DateTime.Now

Ensure.IsNotDefault(date);
Ensure.IsPast(date);
Ensure.IsFuture(date);

Enum Checks

Ensure.ThrowIfUndefined(status);  // Not a defined enum value
Ensure.IsDefined(status);         // true if defined

Boolean Conditions

For custom conditions not covered by specific methods:

Ensure.ThrowIfTrue(user.IsDeleted, "User is deleted");
Ensure.ThrowIfFalse(user.IsActive, "User is inactive");

Equality Checks

Ensure.AreEqual(expected, actual)     // true if equal
Ensure.AreNotEqual(value1, value2)    // true if not equal

Exception Types

Method Pattern	Exception Type
ThrowIfNull*	ArgumentNullException
ThrowIfEmpty (collections)	ArgumentNullException or ArgumentException
ThrowIf*Range*	ArgumentOutOfRangeException
ThrowIfNegative*	ArgumentOutOfRangeException
ThrowIfPositive	ArgumentOutOfRangeException
ThrowIfZero	ArgumentOutOfRangeException
Other ThrowIf*	ArgumentException

---

Check Methods (Pragmatic.Ensure.Result)

The Pragmatic.Ensure.Result package provides validation methods that return VoidResult<TError> instead of throwing. Use for domain validation where failure is expected.

Installation

dotnet add package Pragmatic.Ensure.Result

Null Checks

Check.NotNull<T, TError>(T? value, TError error)
Check.NotNull<T, TError>(T? value, Func<TError> errorFactory)
// Supports both T : class and T? where T : struct

String Checks

Check.NotNullOrEmpty<TError>(string? value, TError error)
Check.NotNullOrWhiteSpace<TError>(string? value, TError error)
Check.LengthInRange<TError>(string? value, int min, int max, TError error)
Check.Email<TError>(string? value, TError error)
Check.Url<TError>(string? value, TError error, bool requireHttps = false)
Check.Phone<TError>(string? value, TError error)
Check.Match<TError>(string? value, string pattern, TError error)

Numeric Checks

Check.Positive<T, TError>(T value, TError error)    // where T : INumber<T>
Check.NotNegative<T, TError>(T value, TError error) // where T : struct, IComparable<T>
Check.NotZero<T, TError>(T value, TError error)     // where T : struct, IComparable<T>
Check.InRange<T, TError>(T value, T min, T max, TError error)
Check.AtLeast<T, TError>(T value, T minimum, TError error)
Check.AtMost<T, TError>(T value, T maximum, TError error)

Collection Checks

Check.NotNullOrEmpty<T, TError>(IEnumerable<T>? value, TError error)
Check.NotNullOrEmpty<T, TError>(ICollection<T>? value, TError error)
Check.NotNullOrEmpty<T, TError>(IReadOnlyCollection<T>? value, TError error)
Check.NotNullOrEmpty<T, TError>(T[]? value, TError error)

Other Checks

// Guid
Check.NotEmpty<TError>(Guid value, TError error)

// Enum
Check.Defined<TEnum, TError>(TEnum value, TError error)

// Boolean conditions
Check.That<TError>(bool condition, TError error)
Check.That<TError>(bool condition, Func<TError> errorFactory)
Check.Not<TError>(bool condition, TError error)

// DateTime
Check.InPast<TError>(DateTime value, TError error)
Check.InFuture<TError>(DateTime value, TError error)
Check.InPast<TError>(DateTimeOffset value, TError error)
Check.InFuture<TError>(DateTimeOffset value, TError error)
Check.NotDefault<TError>(DateTime value, TError error)
Check.NotDefault<TError>(DateTimeOffset value, TError error)

// Equality
Check.Equal<T, TError>(T? value1, T? value2, TError error)
Check.NotEqual<T, TError>(T? value1, T? value2, TError error)

Usage Example

using Pragmatic.Ensure.Result;

// Composable validation chain
var result = Check.NotNull(user, new NotFoundError("User not found"))
    .Bind(_ => Check.NotNullOrEmpty(user.Email, new ValidationError("Email required")))
    .Bind(_ => Check.Email(user.Email, new ValidationError("Invalid email format")));

if (result.IsFailure)
{
    return result.Error;
}