var_Create

Create a variable.

ZVAR CExtAPI::var_Create(long VarID, const char* lpVarName);

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

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.

ZVARs never go 'out of scope', so your plugin is responsible for deleting variables when they are no longer needed using the 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.

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

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 var_Create, var_CreateTemp or 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.