Skip to main content

IfNull

Function IfNull(const aValue1, aValue2: Variant): Variant

Example​

procedure ScriptEvent(var Value: variant);
var
  PreferredValue: variant;
begin
  PreferredValue := Null;
  Value := IfNull(PreferredValue, 25);
  // Integer Variant containing 25
end;

Usage​

IfNull returns the fallback Variant only when the first Variant compares equal to Null.

Parameters

NameTypeDescription
aValue1Variant, constPreferred value compared with Variant Null using Velox equality rules.
aValue2Variant, constFallback returned when that equality is true.

Both argument expressions are evaluated before selection. IfNull(Value, ExpensiveFallback()) always evaluates ExpensiveFallback, even when Value is not Null.

Returns

The selected Variant, normally retaining its type, including string, numeric, date, Boolean, Empty or Null. If both arguments are Null, the result is Null.

Errors

Null comparison under ncrError, custom Variant comparison/copy errors, argument evaluation failures and allocation errors propagate. The fallback is not an error handler.

Usage notes

Use IfNull when a database-style Null alone means absent and retaining the selected type matters. Use IfEmpty when exact empty text conversion should also select the fallback, or CoalesceEmpty when whitespace-only strings should count as empty.

Additional Technical Info​

IfNull returns aValue2 only when aValue1 compares equal to Variant Null; otherwise it returns aValue1. The selected Variant is copied without deliberate conversion, so its type is preserved.

It does not treat Empty/unassigned, empty text, whitespace, zero or False as Null. The example is fictional, deterministic and source-reviewed and was not executed by the documentation workflow.

Implementation

The compile/runtime import points directly to vxCommon.IfNull:

if aValue1 = Null then
  Result := aValue2
else
  Result := aValue1;

No VarIsNull, text conversion, trimming, cloning of referenced objects or exception handling is performed.

Selection matrix with default ncrLoose equality

aValue1Result
NullaValue2
Empty/unassigned VariantOriginal Empty Variant
''Original empty-string Variant
Whitespace-only stringOriginal whitespace string
0Original numeric zero and numeric subtype
FalseOriginal Boolean Variant
Any other non-Null valueOriginal first Variant

Global Null-equality dependency

Installed Delphi initializes process-global System.Variants.NullEqualityRule to ncrLoose, where Null equals only Null. The implementation depends on that setting:

  • ncrStrict: every equality involving Null is false, so a Null first value is returned rather than replaced.
  • ncrError: equality involving Null raises EVariantInvalidNullOpError.

Velox source does not assign this variable. A direct VarIsNull implementation would be independent of the rule, but this function does not use one. Callers normally see the documented default unless native code in the process changes it.

Type and reference semantics

The selected Variant is assigned to the result using normal Variant copy semantics. Scalar/string contents are value/reference-counted as defined by Delphi. Interface/object/array-like Variant contents are not deep-cloned; selecting them does not create an independent business object.

Side effects

The function body only compares and copies. Both inputs are eager, and custom Variant equality/copy logic can execute code outside the helper.

Performance and concurrency

Constant-time comparison and Variant copy for ordinary scalar values. Reference counting may occur. Behavior shares the process-global Null comparison rule and can change if native code mutates it concurrently.

Related entries

External references

Created 2026-07-15