Copy qualifier for subroutine parameters
There are two types of parameters to SOUL methods and complex subroutines:
- Input parameters
- Output parameters (also called InOut)
The default parameter type is Input.
If Output is specified for a parameter,
references to the parameter in a method or
complex subroutine directly reference the corresponding parameter in
the Call statement.
As a result, changes to the output parameter are
immediately reflected in the Call variable, and vice versa.
For example, if a Common variable is passed to a User Language Complex subroutine, all changes to the Common variable also affect the parameter:
%common is float common ... %common = 7 call unusual(%common) ... subroutine unusual(%parm is float output) ... %common is float common ... %common = 11 print %parm
In this example, when the indicated call is made to Unusual,
the subroutine would print 11, because %parm is an
output parameter and thus a reference to the Call argument (%common).
As modifying the Call argument affects the output parameter, so does
modifying the output parameter affect the Call argument:
%common is float common ... %common = 7 call unusual(%common) ... subroutine unusual(%parm is float output) ... %common is float common ... %parm = 13 print %common
The print output here is 13, because setting %parm
directly sets %common.
Unlike Output parameters, the Input parameters in non-OO complex subroutines and in method input parameters that are Arrays are not allowed to be updated. This is one of the two main problems with these Input parameters:
- It is often useful to be able to update an Input parameter as if it were a local variable.
- Sometimes Model 204 passes Input parameters as references to the Call argument. This can cause strange behavior if the Call argument changes (because the Call argument is a Common variable, for example).
To circumvent these problems, SOUL provides the Copy qualifier for complex subroutine and method array parameters. The Copy qualifier indicates that:
- A copy of the input parameter is always made.
- The copy of the input parameter is updateable.
The following example demonstrates a use of the Copy qualifier on a method parameter:
subroutine log(%message is string len 255 copy) %message = $time with ' ' with %message %displayJournal(%message) end subroutine print %message
The Print of %message would contain the called message without the time.
Implicitly, all SOUL non-array method input parameters are treated as if Copy were specified for them. This includes the input value for a property Set method: a copy is always made of the input value, and the input value variable may be updated inside the Set method.