Comparison Guards
Learn to use SGuard's comparison guards for range and relational validation.
Overview
SGuard provides comparison guards that work with any IComparable<T> type:
LessThan:value < otherLessThanOrEqual:value <= otherGreaterThan:value > otherGreaterThanOrEqual:value >= otherOutOfRange: outside an inclusive range (value < min || value > max)Between: inside an inclusive range (min <= value <= max)
For numbers there are also sign guards, Negative (< 0), NegativeOrZero (<= 0) and Zero, and for any
type Equal and NotEqual.
For strings, the Is.* comparisons, OutOfRange, Between, Equal and NotEqual have overloads that take a
StringComparison. The four ThrowIf relational guards don't; see String Comparisons.
ThrowIf.* throws when its condition is true: ThrowIf.LessThan(x, 0) throws if x < 0, and returns x
otherwise. The built-in exceptions (LessThanException, OutOfRangeException, NegativeException, ...) derive from
ArgumentOutOfRangeException, and so from ArgumentException.
Numeric Comparisons
Basic Usage
ThrowIf.LessThan(age, 0);
ThrowIf.GreaterThan(quantity, maxQuantity);
var pageSize = ThrowIf.OutOfRange(request.PageSize, 1, 100);
bool isValid = Is.Between(score, 0, 100);
bool isPositive = Is.GreaterThan(value, 0);
The generic guards require TLeft : IComparable<TRight>. decimal doesn't implement IComparable<int>, so
ThrowIf.LessThan(price, 0) with a decimal price doesn't compile (CS0315). Use a literal of the same type: 0m,
0.0 for double, 0f for float. For comparisons with zero, the sign guards avoid the question.
Sign Guards
ThrowIf.Negative(balance); // throws if balance < 0
ThrowIf.NegativeOrZero(quantity); // throws if quantity <= 0
ThrowIf.Zero(divisor); // throws if divisor == 0
bool overdrawn = Is.Negative(balance);
They work with every number type (int, decimal, double, BigInteger, ...). Negative zero (-0.0) is zero:
Negative lets it pass, NegativeOrZero and Zero reject it. Like the other comparisons, NaN fails Negative and
NegativeOrZero.
Range Validation with OutOfRange and Between
Both range guards are inclusive:
// Throws if value is outside [min, max]: the range check you usually want
ThrowIf.OutOfRange(value, min, max);
// Checks if value is in [min, max]
bool inRange = Is.Between(value, min, max);
// Throws if value IS within range
ThrowIf.Between(value, min, max);
ThrowIf.Between throws when the value is inside the range. It does not enforce a range: ThrowIf.Between(age, 18, 120) rejects every valid age and lets 5 through. To require min <= value <= max, use OutOfRange:
ThrowIf.OutOfRange(age, 18, 120);
// or, with your own exception
ThrowIf.OutOfRange(age, 18, 120, () => new DomainException("Members must be between 18 and 120."));
Examples:
Is.Between(5, 1, 10); // true (5 is in range)
Is.Between(1, 1, 10); // true (min is allowed)
Is.Between(10, 1, 10); // true (max is allowed)
Is.Between(0, 1, 10); // false (0 is outside range)
If min is greater than max, Between and OutOfRange throw an ArgumentException ("The minimum must be
less than or equal to the maximum.") instead of silently treating every value as out of range. This check runs when
min and max have the same type, and for the string overloads.
NaN Values
If any operand is a floating-point NaN (double, float, Half or NFloat), every Is.* comparison returns false
(Is.OutOfRange returns true) and every ThrowIf.* comparison throws:
Is.GreaterThan(double.NaN, 100.0); // false
Is.Between(double.NaN, 0.0, 100.0); // false
ThrowIf.GreaterThan(double.NaN, 100.0); // throws GreaterThanException
ThrowIf.OutOfRange(double.NaN, 0.0, 100.0); // throws OutOfRangeException
ThrowIf.Negative(double.NaN); // throws NegativeException
A check written as "reject if too large" with Is.* lets NaN through, because the comparison returns false:
if (Is.GreaterThan(amount, max)) { /* reject */ } // NaN is NOT rejected
Use ThrowIf.GreaterThan(amount, max) or ThrowIf.OutOfRange(amount, min, max), or test that the value is inside
the allowed range with if (Is.OutOfRange(amount, min, max)) { /* reject */ }, which also rejects NaN.
String Comparisons
Culture-Aware Comparisons
String comparison guards accept StringComparison for proper cultural/ordinal handling:
// Ordinal comparison
bool before = Is.LessThan("apple", "banana", StringComparison.Ordinal);
// Case-insensitive comparison
bool less = Is.LessThan("Apple", "banana", StringComparison.OrdinalIgnoreCase);
// Culture-aware comparison
bool cultureLess = Is.LessThan("straße", "strasse", StringComparison.InvariantCulture);
Throw on Invalid Ordering
ThrowIf.OutOfRange, ThrowIf.Between, ThrowIf.Equal and ThrowIf.NotEqual take a StringComparison. For the
relational guards, test with Is.*:
// Throws because "zebra" > "apple"
if (Is.GreaterThan("zebra", "apple", StringComparison.Ordinal))
{
throw new InvalidOperationException("Out of order");
}
// Throws if the code is outside "A00".."W99"
ThrowIf.OutOfRange(code, "A00", "W99", StringComparison.Ordinal);
// Throws if the code IS inside the reserved range
ThrowIf.Between(code, "X00", "X99", StringComparison.Ordinal);
// Throws unless the currencies match, ignoring case
ThrowIf.NotEqual(payment.Currency, order.Currency, StringComparison.OrdinalIgnoreCase);
String comparisons are lexicographic. Don't use them for version numbers ("10.0.0" is less than "2.0.0"), prefixes
or paths; see String Comparisons.
DateTime Comparisons
DateTime now = DateTime.UtcNow;
DateTime deadline = GetDeadline();
ThrowIf.GreaterThan(now, deadline, () => new InvalidOperationException("Deadline has passed"));
bool isExpired = Is.LessThan(expiryDate, DateTime.UtcNow); // expiry date is in the past
Equality
Equal and NotEqual compare with EqualityComparer<T>.Default, so records and other types with value equality work:
ThrowIf.Equal(transfer.TargetAccount, transfer.SourceAccount); // a transfer to the same account
ThrowIf.NotEqual(invoice.Total, payment.Amount, () => new PaymentMismatchException(invoice.Id));
null operands are allowed, and two null values are equal.
Custom IComparable Types
Any type implementing IComparable<T> works, including System.Version:
Version current = new Version(2, 1);
Version minimum = new Version(2, 0);
ThrowIf.LessThan(current, minimum);
bool isNewer = Is.GreaterThan(current, minimum); // true
Your own types work the same way:
public sealed class ApiLevel : IComparable<ApiLevel>
{
public ApiLevel(int major, int minor)
{
Major = major;
Minor = minor;
}
public int Major { get; }
public int Minor { get; }
public int CompareTo(ApiLevel? other)
{
if (other is null) return 1;
int byMajor = Major.CompareTo(other.Major);
return byMajor != 0 ? byMajor : Minor.CompareTo(other.Minor);
}
}
ThrowIf.LessThan(new ApiLevel(2, 1), new ApiLevel(2, 0)); // doesn't throw
Real-World Examples
Age Validation
public class User
{
public string Username { get; }
public int Age { get; }
public User(string username, int age)
{
Username = ThrowIf.NullOrWhiteSpace(username);
Age = ThrowIf.OutOfRange(age, 0, 130);
}
}
Quantity Validation
public void AddToCart(Product product, int quantity)
{
ThrowIf.Null(product);
ThrowIf.NegativeOrZero(quantity, () => new ArgumentException("Quantity must be positive", nameof(quantity)));
ThrowIf.GreaterThan(quantity, product.StockQuantity, () => new InvalidOperationException("Insufficient stock"));
// Add to cart...
}
Price Range Validation
public void SetPrice(decimal price)
{
const decimal MinPrice = 0.01m;
const decimal MaxPrice = 10000m;
Price = ThrowIf.OutOfRange(price, MinPrice, MaxPrice);
}
Date Range Validation
public void ScheduleMeeting(DateTime start, DateTime end)
{
DateTime now = DateTime.UtcNow;
ThrowIf.LessThan(start, now, () => new ArgumentException("Start time must be in the future"));
ThrowIf.LessThanOrEqual(end, start, () => new ArgumentException("End time must be after start time"));
// Schedule meeting...
}
Discount Percentage Validation
public class DiscountCalculator
{
public decimal ApplyDiscount(decimal amount, decimal discountPercent)
{
ThrowIf.OutOfRange(discountPercent, 0m, 100m);
return amount * (1 - discountPercent / 100);
}
}
Combining with Callbacks
ThrowIf.LessThan(
value,
threshold,
SGuardCallbacks.OnFailure(() => logger.LogWarning("Value below threshold")));
bool isValid = Is.Between(
score,
0,
100,
SGuardCallbacks.OnSuccess(() => metrics.Increment("valid.score")));
Best Practices
- Use
ThrowIf.OutOfRangefor range checks: It's clearer than combining LessThan and GreaterThan; remember thatThrowIf.Betweenthrows when the value is inside the range - Specify StringComparison: Always explicit with string comparisons, and never use string ordering for versions, prefixes or paths
- Prefer
ThrowIf.*orIs.OutOfRangefor floating-point input: They reject NaN;if (Is.GreaterThan(...))doesn't - Consider inclusive semantics: Remember Between is inclusive on both ends
- Combine with custom exceptions: Pass a factory (
() => new DomainException(...)) for domain rules
Common Patterns
Exclusive Range Check
Since Between is inclusive, use boolean checks for exclusive ranges:
// Exclusive: min < value < max
if (Is.GreaterThan(value, min) && Is.LessThan(value, max))
{
// value is in exclusive range
}
Clamping Values
// Ensure value stays within bounds
if (Is.OutOfRange(value, min, max))
{
value = Is.LessThan(value, min) ? min : max;
}
Next Steps
- Collection Validation - Any/All guards
- String Comparisons - Deep dive into string handling
- Custom Exceptions - Use domain exceptions