====== var_CopyValue ======

===== Description =====

Copy the value of one variable to another.


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

<code>bool CExtAPI::var_CopyValue(ZVAR hVarDest, ZVAR hVarSrc);</code>

===== Arguments =====

^ Name ^ Type ^ Comment ^
| hVarDest | ZVAR | A ZVAR handle to the destination variable, the value of which will be overwritten. |
| vVarSrc | ZVAR | A ZVAR handle to the source variable, the value of which will overwrite the value of //hVarDest//. |


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

False if:
  * Either the source or destination variables are invalid handles.
  * The source variable is not initialised.
  * The variable type cannot be copied (see below).
True otherwise.


===== Comments =====

==== Function will re-initialise hVarDest if required ====

If //hVarDest// is not of the same variable type as //hVarSrc//, it will automatically be re-initialised as the correct type. 

==== Function does not copy name ====

The name of the variable is not changed by var_CopyValue.




==== Incompatible types ====

The following [[zeolite:varID|variable types]] cannot be copied by var_CopyValue:

^ Type ^ Reason ^
| VarID_void | Voids contain no data, and hence no value to copy. |
| VarID_map | Maps are potentially too big to create multiple copies*. |
| VarID_ProgBox | No copy operator is defined for progress dialogs*.  |
| VarID_ZeoFunc | No copy operator is defined for Zeolite extension functions*.  |

* If you want to create a variable that can be used to access another variable of one of these types, use [[zeolite:functions:var_SetVarRef]] instead.