index

References

Parameter references may not have the same meaning in AngelScript as they do in C++. Because AngelScript must at all times guarantee that the references are valid, some restrictions have been added. The declaration of the parameter reference must use one of the keywords in, out, or inout.

reference description
type &in This form always makes a copy of the value and passes the address of the copy.
const type &in This form makes a copy, only if the life time of the value is not guaranteed, e.g. it is not a local variable, or it doesn't support object handles. This is the form that has the most advantages, as most of the time the value doesn't have to be duplicated, and there is no restriction to the expressions that can be used.
type &out This form passes the address of a dummy value. When the function returns the value is copied to the reference in the argument expression. The expression is also evaluated only after the function returns. This is the preferred way to allow functions to return multiple values.
const type &out This form is useless, since the function wouldn't be able to alter the value in the parameter.
type &inout This form always passes the address of the true value. But if the life time of the value is not guaranteed the compiler will give an error. Local variables and object types that support object handles always have their life time guaranteed. It's recommended to use this form only with object types that support object handles.
const type &inoutSame as above, except the function will not be able to alter the value.

Unsafe references

If the application wants parameter references that work like they do in C++, then the script library can be compiled with the flag AS_ALLOW_UNSAFE_REFERENCES defined. When this is done, the parameter references can be declared without the in, out, or inout. The parameter references declared without any of the keywords will always pass the address to the original value, and will not have any restrictions to the expressions that can be used. The parameter references with the in and out keywords will still work like before, but the refernces with the inout keyword will have the restrictions removed so that they work just like normal C++ references.

The application writer and script writer has to be aware that it is possible to write scripts that access invalid references when the library is compiled in this mode, just like it is possible to do so in C++.

top