====== zvar_SetVarRef ======

===== Description =====

Set a variable to be a reference (alias) of another variable. 

===== Files =====

^ Declaration | ''Zeolite.h'' |
^ Implementation | ''Zeolite.cpp'' |

===== Function prototype =====

<code="C">bool zvar_SetVarRef(ZVAR hPtrVar, ZVAR hSrcVar);</code>

===== Arguments =====

^ Name ^ Type ^ Comment ^
| hPtrVar | ZVAR | A ZVAR handle to a variable, which will become the reference/alias of //hSrcVar//. |
| hSrcVar | ZVAR | A ZVAR handle to a variable, which is to be referenced by //hPtrVar//. |

===== Return value =====

False if an error occurred, and true otherwise.

===== Comments =====

==== Use this function for... ====

This function is normally used to [[wp>Pass-by-reference#Call_by_reference|pass values by reference]] to functions when they either cannot be copied using [[zeolite:functions:zvar_CopyValue]] (such as a map), or when it is excessively wasteful to do so (such as for a very large varlist.) Please refer to the [[#example]] provided below. 

==== Automatic initialisation ====

If //hPtrVar// is not initialised as the variable type of //hSrcVar//, it will be automatically re-allocated as the appropriate type. 

==== Name is not changed ====

This function does not change the name of //hPtrVar//, so //hPtrVar// and //hSrcVar// may have different names. 

==== Using zvar_Delete ====

The [[zeolite:functions:zvar_Delete]] function may be safely used on variables that are references of another, as the real instance of the data is only deleted from the original variable.

===== Example =====

This example was taken from the [[bundywiki>plugins:calc:SphericalDistort|SphericalDistort]] plugin:

<code>
// create a temporary list to hold the arguments for the SphericalDistort function
ZLIST hArgs = zvar_Create(VarID_varlist);
if(!hArgs) {
    return false;
}

// get a handle to the heightfield in the project
ZVAR hMap = zproj_GetMap("HF");
if(!hMap) {
    return false;
}

// create a map handle in the function argument list
ZVAR hMap2 = zlist_CreateItem(hArgs, VarID_map, "hMap");
if(!hMap2) {
    return false;
}

// Use SetVarRef to make "hMap" in the function argument list point to the data 
// of the map at "HF" (the project heightfield)
if(!zvar_SetVarRef(hMap2, hMap)) {
    return false;
}

// set the radius
double radius = 6400*1000; // radius of earth
ZVAR hRad = zlist_CreateItem(hArgs, VarID_double, "radius");
if(!hRad) {
    return false;
}
if(!zvar_SetValue(hRad, &radius)) {
    return false;
}
if(!zvar_EditUI(hRad, "Enter sphere radius in metres", NULL, NULL)) {
    bool TempBool = false;
    zvar_SetValue(hRval, &TempBool);
    return true; // function returned safely, but the zeolite rval is OK
}

// now pass the argument list to the function and execute it
bool rval = SphericalDistort(hRval, hArgs);

// delete the temporary argument list
zvar_Delete(hArgs);

// all done, lets go home
return rval;
</code>