Skip to main content

VarToStrDef

Function VarToStrDef( const V : Variant; const ADefault : string) : string

Example​

procedure ScriptEvent(var Value: variant);
begin
  Value := VarToStrDef(Null, '(missing)'); // (missing)
end;

Usage​

VarToStrDef converts a Variant to Velox string and returns a caller-supplied value only for Null.

Parameters and result

ItemTypeDescription
VVariant (const)Value to test for Null and otherwise convert.
ADefaultstring (const)Exact result returned when V is Null. It is not used for Empty or conversion failure.
ResultstringADefault for Null; otherwise the converted Velox string.

Errors

The function does not catch a failed conversion. Variant arrays, incompatible interfaces/custom types, range/conversion failures and other non-Null errors propagate as EVariantError items. It also does not protect against allocation failure while constructing the result.

Additional Technical Info​

VarToStrDef returns ADefault when V is Null. For every non-Null value it performs the same Delphi Variant-to-native-string conversion used by VarToStr.

The example is fictional and source-reviewed only.

Implementation

The Velox wrapper delegates to System.Variants.VarToStrDef. Delphi calls its Null predicate first. A Null value bypasses the cast and returns ADefault; any other value is assigned to the string result through Delphi's normal Variant conversion engine.

This means ADefault is a Null policy, not a general error default.

Behaviour and quirks

  • Empty/Unassigned is not Null and normally converts to '' rather than ADefault.
  • Empty text remains empty text. Zero and false produce their own textual representations.
  • Unlike VarToStr, the Null branch does not read NullAsStringValue; it always uses this call's ADefault.
  • Non-Null numeric, date, Currency and Boolean formatting retains the host-dependent rules described for VarToStr.
  • If ADefault is also a possible real conversion result, the caller cannot tell from the returned text whether the source was Null. Test VarIsNull first when provenance matters.

Performance and concurrency

The Null branch returns a managed-string copy/reference of ADefault; other paths have the allocation and formatting cost of the source type. The function has no mutation or I/O, but non-Null formatting can read process-wide locale and Variant settings.

Related entries

  • VarToStr uses Delphi's process-global Null string value.
  • VarToWideStrDef provides the same Null-only contract for WideString.
  • VarIsNull distinguishes the fallback branch explicitly.

External references

Created 2026-07-15