====== var_Create ======

===== Description =====

Create a variable.

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

<code>ZVAR CExtAPI::var_Create(long VarID, const char* lpVarName);</code>

===== Arguments =====

^ Name ^ Type ^ Comment ^
| VarID | long | The [[zeolite:VarID|type ID]] of the variable to be created. |
| lpVarName | const char* | A pointer to a C-style string containing the name of the variable to be created (null if to be unnamed). |

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

Null if an error occurred, and a non-NULL ZVAR handle otherwise.

===== Comments ====

==== Nested lists ====

If the given //lpVarName// contains the '.' (dot) character, the variable will be created in a nested list. For instance, and //lpVarName// of "list1.list2.varname" will create the variable //varname// in a list called //list2//, which itself is contained in //list1//. In this example, //list1// and //list2// will be automatically created if they do not already exist. If //list1// or //list2// do exist but are not initialised as something other than VarID_varlist, var_Create will return false and error will be thrown.


==== Garbage collection ====

ZVARs never go 'out of scope', so your plugin is responsible for deleting variables when they are no longer needed using the [[zeolite:functions:var_Delete]] function. If your plugin doesn't delete its variables, L3DT will do the garbage collection when it closes, and it may mock you for not cleaning up after yourself.

<note>
To restore normal scoping rules, use the C++ wrapper classes ([[zeolite:classes:CzVar]], [[zeolite:classes:CzStr]], [[zeolite:classes:CzMap]]). These classes automatically delete their variable handles when going out of scope, so you don't have to.
</note>

==== Shared/private access ====

Variables created by var_Create are placed into a shared memory space that can be accessed by L3DT or other plugins using [[zeolite:functions:var_GetVar]], [[zeolite:functions:var_Delete]], etc. If you want to create a private variable accessible only to your plugin, use [[zeolite:functions:var_CreateTemp]], and store the ZVAR in your plugin for later use (note [[zeolite:functions:var_GetVar]] cannot retrieve a variable created with [[zeolite:functions:var_CreateTemp]].)


==== Variable size ====

A variable created with var_Create occupies more memory than using, say, the //new// operator in C++. This is because the ZVAR structure stores, in addition to the data, such things as the variable type and name string. Thus, if you wish to create a large array of variables (e.g. a million floats) you should not use [[zeolite:functions:var_Create]], [[zeolite:functions:var_CreateTemp]] or [[zeolite:functions:list_CreateItem]] for each item in the array, but instead use the provided buffer functions (CExtAPI::buffer_xxx), which store the data in an array without decoration.