VarSetStrCapacity

Enlarges the memory a variable keeps for native code, or frees it. This is not normally needed, but may be used with DllCall or SendMessage.

GrantedCapacity := VarSetStrCapacity(&TargetVar , RequestedCapacity)

Parameters

&TargetVar

Type: VarRef

A reference to a variable. For example: VarSetStrCapacity(&MyVar, 1000). This can also be a function's ByRef parameter, or a dynamic reference such as &MyArray%i% to a variable outside the function.

RequestedCapacity

Type: Integer

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 number of characters that the variable should be able to hold after the adjustment. RequestedCapacity does not include the internal zero terminator. For example, specifying 1 would allow the variable to hold up to one character in addition to its internal terminator. Note: the variable will auto-expand if the script assigns it 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 will still made blank for consistency).

Therefore, to explicitly shrink a variable, first free its memory with VarSetStrCapacity(&Var, 0) and then use VarSetStrCapacity(&Var, NewCapacity) -- or simply let it auto-expand from zero as needed.

Assigning a value to the variable keeps its memory, which grows when the value does not fit. VarSetStrCapacity(&Var, 0) frees it and returns 0.

Specify -1 for RequestedCapacity to set the variable to the text in its memory, up to the first null character. This is useful in cases where the string has been altered indirectly, such as by passing its address via DllCall or SendMessage. In this mode, VarSetStrCapacity returns the variable's new length rather than the capacity. For a variable holding a number, it returns the length of the number's string form and leaves the number in place.

Return Value

Type: Integer

This function returns the number of characters that TargetVar can now hold, which will be greater than or equal to RequestedCapacity.

Failure

An exception is thrown under any of the following conditions:

• TypeError: TargetVar is neither a VarRef nor an object with a __Value property.
• TypeError: A capacity above 0 is requested for something which has no memory of its own to size, such as a property or built-in variable reference. Dynamic references to locals and statics, and aliases imported through one or more modules, retain the original variable's memory.
• TypeError: RequestedCapacity is omitted and the variable holds a number or an object.
• The requested capacity is too large to fit within any single contiguous memory block available to the script. In rare cases, this may be due to the system running out of memory.
• ValueError: RequestedCapacity is less than -1, or is 2147483647 or greater.

Remarks

The Buffer object offers superior clarity and flexibility when dealing with binary data, structures, DllCall and similar. For instance, a Buffer object can be assigned to a property or array element or be passed to or returned from a function without copying its contents.

Capacity applies to the native memory used by StrPtr and Str/WStr arguments, not concatenation. With -1, a different string assigned since the memory was last synchronized takes precedence, up to its first null; reassigning the string already held preserves native writes. See StrPtr's synchronization rules.

Related

Buffer object, DllCall, NumPut, NumGet

Examples

max_chars := 10

Loop 2
{
    ; Allocate space for use with DllCall.
    VarSetStrCapacity(&buf, max_chars)

    if (A_Index = 1)
        ; Alter the variable indirectly via DllCall.
        DllCall("wsprintf", "Ptr", StrPtr(buf), "Str", "0x%08x", "UInt", 4919, "CDecl")
    else
        ; Use "str" to update the length automatically:
        DllCall("wsprintf", "Str", buf, "Str", "0x%08x", "UInt", 4919, "CDecl")

    ; Concatenate a string to demonstrate why the length needs to be updated:
    wrong_str := buf . "<end>"
    wrong_len := StrLen(buf)

    ; Update the variable's length.
    VarSetStrCapacity(&buf, -1)

    right_str := buf . "<end>"
    right_len := StrLen(buf)

    MsgBox
    (
    "Before updating
      String: " wrong_str "
      Length: " wrong_len "

    After updating
      String: " right_str "
      Length: " right_len
    )
}