Is API
Complete reference for boolean-returning guard methods.
Overview
Is provides guard methods that return bool values for conditional logic. Every method takes an optional
SGuardCallback as its last regular parameter. The callback receives GuardOutcome.Success when the method returns
true and GuardOutcome.Failure when it returns false; see Outcome mapping.
Is.* does not throw for a false result, but it still throws for invalid arguments:
| Situation | Exception |
|---|---|
null comparison operand, bound, collection or predicate | ArgumentNullException |
Between with min greater than max (bounds of the same type, or the string overloads) | ArgumentException |
Is.Email with a null email (or regex) | ArgumentNullException |
Is.Email with an empty email (or regex) | ArgumentException |
Is.Email custom pattern that runs past its match timeout | RegexMatchTimeoutException |
null string for LongerThan or ShorterThan, or a negative length | ArgumentNullException, ArgumentOutOfRangeException |
Is.Match with a null or invalid pattern, or a match that runs past its timeout | ArgumentException, RegexMatchTimeoutException |
In these cases the callback is not invoked.
NullOrEmpty
Returns true if the value is null or empty.
Overloads
bool Is.NullOrEmpty<T>(T? value, SGuardCallback? callback = null);
bool Is.NullOrEmpty<T>(ReadOnlySpan<T> value, SGuardCallback? callback = null);
bool Is.NullOrEmpty<T>(T? value, Expression<Func<T, object>> selector, SGuardCallback? callback = null);
What counts as empty
Without a selector, a value is null or empty when it is:
null, ordefault(T): so0,false,Guid.Empty,default(DateTime), the default enum value and any default struct count as empty, also when they are boxed or held by a nullable (int? x = 0andDayOfWeek? d = defaultare empty too);- an empty string (
""); a whitespace-only string is not empty; - an empty array, collection or enumerable, or an empty
Memory<T>orReadOnlyMemory<T>; - a
DateTime,TimeSpan,TimeOnlyorDateTimeOffsetwith zero ticks, orDateOnly.MinValue.
A non-null class instance is not inspected property by property; use a selector for that.
The ReadOnlySpan<T> overload returns true only for an empty span. As with arrays and collections, a span with
elements is not empty, even if all of its elements are null. (Arrays bind to the generic T overload; both give the
same result.)
With a selector:
nullanywhere on the path (includingvalueitself) counts as empty. The path can go through members, indexers, array elements and instance methods (o => o.Items[0].Name.Trim()); other expressions, such as method arguments or the operands of+, are evaluated as written;- the selected member is checked with the rules above; a default
ImmutableArray<T>counts as empty; - a member of a complex type counts as empty only if all of its readable properties are null or empty (recursively; a type already being inspected on the same path, or nested more than 8 levels deep, is only null-checked; indexers are skipped);
- a framework class that is not a collection (a type in a
Systemnamespace, such asUriorVersion) is only checked for null; its properties are not read.
Selectors are compiled once and cached by expression structure, including selectors that capture local variables or
use operators such as + and ??; see Expression Caching.
:::warning Selectors and Native AOT
Selectors don't work under Native AOT, and trimming can remove the properties they read. The selector overloads are
marked [RequiresUnreferencedCode] and [RequiresDynamicCode], so trimmed and AOT apps get a warning. Check the member
directly instead: Is.NullOrEmpty(order.Customer?.Email).
:::
Examples
bool isEmpty = Is.NullOrEmpty(username);
bool hasNoItems = Is.NullOrEmpty(items);
bool missing = Is.NullOrEmpty(order, o => o.Customer.Email);
bool noTags = Is.NullOrEmpty(new ReadOnlySpan<string>(tags));
Null and NullOrWhiteSpace
bool Is.Null<T>(T? value, SGuardCallback? callback = null);
bool Is.NullOrWhiteSpace(string? value, SGuardCallback? callback = null);
Is.Null returns true only for null: unlike NullOrEmpty, "", empty collections and default values such as 0
are not null. Is.NullOrWhiteSpace returns true for null, "" and strings of white space only. Both are annotated
[NotNullWhen(false)], so after if (Is.NullOrWhiteSpace(name)) return; the compiler knows name isn't null.
if (Is.NullOrWhiteSpace(request.Name))
{
errors["name"] = ["A name is required."];
}
Comparison Guards
All comparison guards compare with CompareTo (the StringComparison overloads with string.Compare) and throw
ArgumentNullException when an operand is null.
Overloads
bool Is.LessThan<TLeft, TRight>(TLeft lValue, TRight rValue, SGuardCallback? callback = null)
where TLeft : IComparable<TRight>;
bool Is.LessThan(string lValue, string rValue, StringComparison comparison, SGuardCallback? callback = null);
bool Is.LessThanOrEqual<TLeft, TRight>(TLeft lValue, TRight rValue, SGuardCallback? callback = null)
where TLeft : IComparable<TRight>;
bool Is.LessThanOrEqual(string lValue, string rValue, StringComparison comparison, SGuardCallback? callback = null);
bool Is.GreaterThan<TLeft, TRight>(TLeft lValue, TRight rValue, SGuardCallback? callback = null)
where TLeft : IComparable<TRight>;
bool Is.GreaterThan(string lValue, string rValue, StringComparison comparison, SGuardCallback? callback = null);
bool Is.GreaterThanOrEqual<TLeft, TRight>(TLeft lValue, TRight rValue, SGuardCallback? callback = null)
where TLeft : IComparable<TRight>;
bool Is.GreaterThanOrEqual(string lValue, string rValue, StringComparison comparison, SGuardCallback? callback = null);
LessThan returns true if lValue < rValue, LessThanOrEqual if lValue <= rValue, GreaterThan if
lValue > rValue and GreaterThanOrEqual if lValue >= rValue.
Because the constraint is TLeft : IComparable<TRight>, both operand types matter: Is.LessThan(price, 0) with a
decimal price does not compile (decimal doesn't implement IComparable<int>); write Is.LessThan(price, 0m).
Between
Returns true if min <= value <= max (inclusive).
bool Is.Between<TValue, TMin, TMax>(TValue value, TMin min, TMax max, SGuardCallback? callback = null)
where TValue : IComparable<TMin>, IComparable<TMax>;
bool Is.Between(string value, string min, string max, StringComparison comparison, SGuardCallback? callback = null);
If min is greater than max, Between throws ArgumentException instead of returning false. This is checked when
both bounds have the same type, and always for the string overload.
OutOfRange
Returns true if value < min or value > max, the opposite of Between. Both bounds are inclusive, and a NaN
operand is outside every range.
bool Is.OutOfRange<TValue, TMin, TMax>(TValue value, TMin min, TMax max, SGuardCallback? callback = null)
where TValue : IComparable<TMin>, IComparable<TMax>;
bool Is.OutOfRange(string value, string min, string max, StringComparison comparison, SGuardCallback? callback = null);
Like Between, it throws ArgumentException when min is greater than max.
Sign checks
bool Is.Negative<T>(T value, SGuardCallback? callback = null) where T : INumber<T>; // value < 0
bool Is.NegativeOrZero<T>(T value, SGuardCallback? callback = null) where T : INumber<T>; // value <= 0
bool Is.Zero<T>(T value, SGuardCallback? callback = null) where T : INumberBase<T>; // value == 0
They work with every number type. Negative zero (-0.0) is zero, not negative. Like the other comparisons, NaN returns
false.
Equal and NotEqual
bool Is.Equal<T>(T lValue, T rValue, SGuardCallback? callback = null);
bool Is.Equal(string? lValue, string? rValue, StringComparison comparison, SGuardCallback? callback = null);
bool Is.NotEqual<T>(T lValue, T rValue, SGuardCallback? callback = null);
bool Is.NotEqual(string? lValue, string? rValue, StringComparison comparison, SGuardCallback? callback = null);
Values are compared with EqualityComparer<T>.Default. null operands are allowed, and two null values are equal.
NaN
If any operand is a floating-point NaN (double, float, Half or NFloat), every comparison, Between and the
sign checks return false, and OutOfRange returns true.
Keep this in mind when the check rejects on true:
// NaN gets through: Is.GreaterThan(double.NaN, max) is false
if (Is.GreaterThan(amount, max)) return Reject();
// NaN is rejected
if (!Is.Between(amount, 0.0, max)) return Reject();
ThrowIf.* comparisons throw on NaN, so they are the safer choice for argument validation.
Examples
bool isNegative = Is.LessThan(value, 0);
bool inRange = Is.Between(age, 0, 130);
bool before = Is.LessThan("apple", "banana", StringComparison.Ordinal);
if (Is.GreaterThanOrEqual(balance, cost))
{
// Sufficient balance
}
Don't use string comparisons for access-control or path-prefix checks, or to compare version numbers; see String Comparisons.
Collection Guards
Overloads
bool Is.Any<T>(IEnumerable<T> source, Func<T, bool> predicate, SGuardCallback? callback = null);
bool Is.Any<T>(ReadOnlySpan<T> source, Func<T, bool> predicate, SGuardCallback? callback = null);
bool Is.All<T>(IEnumerable<T> source, Func<T, bool> predicate, SGuardCallback? callback = null);
bool Is.All<T>(ReadOnlySpan<T> source, Func<T, bool> predicate, SGuardCallback? callback = null);
Any returns true if at least one element matches the predicate; All returns true if every element
matches. Both follow LINQ semantics for empty input: Is.Any returns false and Is.All returns true, for the
IEnumerable<T> and ReadOnlySpan<T> overloads alike. On C# 14, arrays bind to the ReadOnlySpan<T> overloads; the
result is the same.
Examples
bool hasNull = Is.Any(items, i => i is null);
bool allPositive = Is.All(numbers, n => n > 0);
if (Is.Any(users, u => u.IsAdmin))
{
// At least one admin exists
}
Enums and lengths
bool Is.NotDefined<TEnum>(TEnum value, SGuardCallback? callback = null) where TEnum : struct, Enum;
bool Is.LongerThan(string value, int maxLength, SGuardCallback? callback = null);
bool Is.ShorterThan(string value, int minLength, SGuardCallback? callback = null);
NotDefined returns true if the enum has no member with this value (Enum.IsDefined; a combination of [Flags]
values counts as defined only if the enum declares it). LongerThan and ShorterThan compare string.Length, the
number of UTF-16 code units.
Email
Returns true if the string looks like an email address.
bool Is.Email(string email, SGuardCallback? callback = null);
bool Is.Email(string email, string regex, RegexOptions? regexOptions = null, SGuardCallback? callback = null);
bool Is.Email(string email, string regex, RegexOptions regexOptions, TimeSpan matchTimeout,
SGuardCallback? callback = null);
static TimeSpan Is.DefaultEmailRegexTimeout { get; } // 1 second
- The first overload uses a built-in ASCII pattern: at most 254 characters, at most 64 before the
@, no trailing line break, a domain with a top-level part of two or more letters. It is a practical filter, not a complete RFC 5322 validator. - The custom-pattern overloads run your
regexwithIs.DefaultEmailRegexTimeout(1 second) or thematchTimeoutyou pass. When the match runs past the timeout,RegexMatchTimeoutExceptionis thrown and the callback is not invoked. - A
nullemail or regex throwsArgumentNullException; an empty one throwsArgumentException.
bool ok = Is.Email("user@example.com"); // true
bool bad = Is.Email("not-an-email"); // false
bool corporate = Is.Email(input, @"^[^@\s]+@example\.com\z", RegexOptions.IgnoreCase);
Url, CreditCard and Match
These validators return false for null and "" and are annotated [NotNullWhen(true)], unlike Is.Email, which
throws for them.
bool Is.Url(string? value, SGuardCallback? callback = null);
bool Is.CreditCard(string? value, SGuardCallback? callback = null);
bool Is.Match(string? value, Regex regex, SGuardCallback? callback = null);
bool Is.Match(string? value, string pattern, RegexOptions options = RegexOptions.None, SGuardCallback? callback = null);
bool Is.Match(string? value, string pattern, RegexOptions options, TimeSpan matchTimeout, SGuardCallback? callback = null);
static TimeSpan Is.DefaultRegexTimeout { get; } // 1 second
Urlreturnstruefor an absolutehttporhttpsURL with a host. Every other scheme fails, includingjavascript:,data:andfile:, so a value that passes is safe to render as a link. Relative and protocol-relative URLs (//example.com) fail, and so does a string with white space, control characters or invisible formatting characters anywhere in it. It parses the string withUri.TryCreate, so unlike most guards it allocates.CreditCardreturnstruefor 12 to 19 digits that pass the Luhn checksum, with optional single spaces or hyphens between digits. It checks the format only: it can't tell whether the card exists or can be charged. Don't log card numbers.Matchreturnstrueif the string matches the regular expression. The pattern is not anchored for you:[0-9]+matches"abc1", so write^...\zto match the whole string. A pattern string is matched withIs.DefaultRegexTimeoutor thematchTimeoutyou pass; aRegexinstance uses its own timeout. Prefer a cached or[GeneratedRegex]instance on hot paths, and don't build patterns from user input.
if (!Is.Url(request.Website))
{
errors["website"] = ["Enter an http or https address."];
}
[GeneratedRegex(@"^[A-Z]{3}\z")]
private static partial Regex CurrencyCode();
bool known = Is.Match(request.Currency, CurrencyCode());
Outcome Mapping
For Is.* methods the callback reports the return value, not whether the input is "valid":
- Returns
true→ callback invoked withGuardOutcome.Success - Returns
false→ callback invoked withGuardOutcome.Failure
So Is.NullOrEmpty(null, callback) reports Success, because the method returned true.
bool valid = Is.Between(value, min, max,
SGuardCallbacks.OnSuccess(() => metrics.Increment("valid"))
+ SGuardCallbacks.OnFailure(() => metrics.Increment("invalid")));
Usage Patterns
Conditional Logic
if (Is.Between(discount, 0, 100))
{
ApplyDiscount(discount);
}
else
{
ShowError("Invalid discount");
}
Boolean Expressions
bool canProceed = Is.GreaterThanOrEqual(balance, cost) &&
Is.All(items, i => i.IsAvailable);
Validation with Custom Errors
if (!Is.Between(age, 18, 100))
{
throw new ValidationException("Age must be between 18 and 100");
}
Metrics and Monitoring
bool isValid = Is.Between(
responseTime,
TimeSpan.Zero,
maxResponseTime,
SGuardCallbacks.OnSuccess(() => metrics.Increment("response.valid"))
+ SGuardCallbacks.OnFailure(() => metrics.Increment("response.slow")));
Performance
Is.*never allocates an exception for afalseresult.- Comparisons call
CompareTodirectly. - Selector-based
NullOrEmptychecks reuse cached compiled selectors, including selectors that capture local variables. See Expression Caching for measurements.
When to Use Is.* vs ThrowIf.*
Use Is.* When:
- Validation failure is expected (normal control flow)
- Implementing conditional logic
- Need to check multiple conditions before acting
Use ThrowIf.* When:
- Validation failure is exceptional
- Validating arguments or invariants
- Want to fail fast with clear exceptions
See Best Practices for detailed guidance.
Next Steps
- ThrowIf API - Exception-throwing guards
- Callbacks API - Callback reference
- Best Practices - Effective usage guidelines