14.4.3 Out parameters

Out parameters (output parameters) are declared as follows:

The purpose of an out parameter is to pass values back to the calling routine: the variable is passed by reference. The initial value of the parameter on function entry is discarded, and should not be used.

If a variable must be used to pass a value to a function and retrieve data from the function, then a variable parameter must be used. If only a value must be retrieved, a out parameter can be used.

Needless to say, default values are not supported for out parameters.

The difference of out parameters and parameters by reference is very small (however, see below for managed types): the former gives the compiler more information about what happens to the arguments when passed to the procedure: it knows that the variable does not have to be initialized prior to the call. The following example illustrates this:

Both procedures DoA and DoB do practically the same. But DoB’s declaration gives more information to the compiler, allowing it to detect that D does not have to initialized before DoB is called. Since the parameter A in DoA can receive a value as well as return one, the compiler notices that C was not initialized prior to the call to DoA:

This shows that it is better to use out parameters when the parameter is used only to return a value.

Remark: Out parameters are only supported in Delphi and ObjFPC mode. For the other modes, out is a valid identifier.

Remark: For managed types (reference counted types), using Out parameters incurs some overhead: the compiler must be sure that the value is correctly initialized (i.e. has a reference count of zero (0)). This initialization is normally done by the caller.