Delphi in a Nutshell

Name

Out Directive

Syntax

Subroutine header(Parameters...; out Name: Type; ...);

Description

The out directive is used in subroutine parameter declarations. It is similar to a var keyword in declaring a parameter the subroutine can change. The difference between var and out is that an out parameter does not pass a meaningful value into the subroutine when the routine is called—it only provides a useful output value when the routine returns.

Tips and Tricks

• Out parameters are often used in COM interfaces.

• Out parameters are useful for reference-counted entities, such as strings, dynamic arrays, and interfaces. Out has slightly improved performance over var because the compiler does not have to increment the reference count when passing the argument to the subroutine. The subroutine must change the value of the variable, and the compiler increments the reference count normally at that time.

• Even if the parameter is not reference counted, you can use the out directive to tell the person who reads or maintains your code that the subroutine does not rely on an input value for that parameter.

Example

type
  ICollection = interface
    ...
    // Every collection can have any number of enumerators that
    // enumerate the items in the collection. The Enum function
    // creates a new enumerator and stores it in the Enumerator
    // argument.
    function Enum(out Enumerator: IEnumerator): HResult;
    ...

See Also

Const Keyword, Interface Keyword, Var Keyword