Enlarges a variable's holding capacity or frees its memory. Normally, this is necessary only for unusual circumstances such as DllCall.
| GrantedCapacity := VarSetCapacity(UnquotedVarName [, RequestedCapacity, FillByte]) |
Parameters
| GrantedCapacity | The length of string that Var can now hold, which will be greater or equal to RequestedCapacity. If VarName is not a valid variable name (such as a literal string or number), 0 is returned. If the system has insufficient memory to make the change, an error dialog will be displayed and the current thread will exit. |
| UnquotedVarName | The name of the variable (not in quotes). For example: VarSetCapacity(MyVar, 1000). This can also be a dynamic variable such as Array%i%. |
| RequestedCapacity | If omitted, the variable's current capacity will be returned and its contents will not be altered. Otherwise, anything currently in the variable is lost (the variable becomes blank). Specify for RequestedCapacity the length of string that the variable should be able to hold after the adjustment. This length does not include the internal zero terminator. For example, specifying 1 would allow the variable to hold up to one character. Note: the variable will auto-expand if it is assigned a larger value later. Since this function is often called simply to ensure the variable has a certain minimum capacity, for performance reasons, it shrinks the variable only when RequestedCapacity is 0. In other words, if the variable's capacity is already greater than RequestedCapacity, it will not be reduced (but the variable is still made blank for consistency). Therefore, to explicitly shrink a variable, first free its memory with VarSetCapacity(Var, 0) and then use VarSetCapacity(Var, NewCapacity) -- or simply let it auto-expand from zero as needed. For performance reasons, freeing a variable whose previous capacity was between 1 and 63 might have no effect because its memory is of a permanent type. In this case, the current capacity will be returned rather than 0. |
| FillByte [v1.0.36.07+] |
This parameter is normally omitted, in which case the memory of the target variable is not initialized (instead, the variable is simply made blank as described above). Otherwise, specify a number between 0 and 255. Each byte in the target variable's memory area (its actual, total capacity) is set to that number. Zero is by far the most common value, which is useful in cases where the variable will hold raw binary data such as a DllCall structure. |
Remarks
In addition to its uses described at DllCall, this function can also be used to enhance performance when building a string by means of gradual concatenation. This is because multiple automatic resizings can be avoided when you have some idea of what the string's final length will be. In such a case, RequestedCapacity need not be accurate: if the capacity is too small, performance is still improved and the variable will begin auto-expanding when the available capacity has been exhausted. If the capacity is too large, some of the memory is wasted; however, all the memory can be freed after the operation by means of VarSetCapacity(Var, 0).
#MaxMem restricts only the automatic expansion that a variable does on its own. It does not affect VarSetCapacity.
Related
Example
VarSetCapacity(MyVar, 10240000) ; ~10 MB
Loop
{
...
MyVar = %MyVar%%StringToConcatenate%
...
}