VarSetCapacity()

Erhöht die Speicherkapazität einer Variable oder gibt ihren Speicher frei. Normalerweise nur in Sonderfällen wie DllCall() notwendig.

GewährteKapazität := VarSetCapacity(ZielVar , GewünschteKapazität, FüllByte)

Parameter

ZielVar

Eine Variablenreferenz. Zum Beispiel: VarSetCapacity(MeineVar, 1000). Dies kann auch eine dynamische Variable wie Array%i% oder ein ByRef-Parameter einer Funktion sein.

GewünschteKapazität

Wenn weggelassen, wird die aktuelle Kapazität der Variable zurückgegeben und ihr Inhalt bleibt unverändert. Andernfalls geht der gesamte Inhalt der Variable verloren (die Variable wird leer gemacht).

Geben Sie für GewünschteKapazität die Anzahl der Bytes an, die die Variable nach der Anpassung enthalten soll. Für Unicode-Zeichenketten muss die doppelte Länge angegeben werden. GewünschteKapazität ist unabhängig vom internen Nullterminator. Zum Beispiel bewirkt die Angabe von 1, dass die Variable bis zu einem Byte zusätzlich zu ihrem internen Terminator enthalten kann. Hinweis: Die Variable wird automatisch erweitert, wenn ihr später vom Skript ein größerer Wert zugewiesen wird.

Da diese Funktion oft nur aufgerufen wird, um eine bestimmte Mindestkapazität für die Variable sicherzustellen, wird die Funktion die Variable aus Performanzgründen nur dann verkleinern, wenn GewünschteKapazität 0 ist. Mit anderen Worten: Wenn die Variablenkapazität bereits größer als GewünschteKapazität ist, wird sie nicht reduziert (wobei die Variable aus Konsistenzgründen weiterhin leer gemacht wird).

Um eine Variable explizit zu verkleinern, ist es daher notwendig, zuerst ihren Speicher mit VarSetCapacity(Var, 0) freizugeben und dann VarSetCapacity(Var, NeueKapazität) zu verwenden -- oder lassen Sie die Variable einfach bei Bedarf automatisch von Null aus erweitern.

Aus Performanzgründen wird eine Variable mit einer ursprünglichen Kapazität von weniger als 64 Zeichen (128 Bytes in Unicode-Builds) in der Regel nicht freigegeben, da ihr Speicher permanenter Natur ist. In diesem Fall wird statt 0 die aktuelle Kapazität zurückgegeben.

Aus Performanzgründen kann der Speicher einer Variable mit einer Kapazität von weniger als 4096 Bytes nicht durch Zuweisung einer leeren Zeichenkette (z.B. Var := "") freigegeben werden. Allerdings kann VarSetCapacity(Var, 0) den Speicher freigeben.

[v1.0.44.03+]: Geben Sie -1 für GewünschteKapazität an, um die intern-gespeicherte Zeichenkettenlänge der Variable auf die Länge des aktuellen Inhalts zu aktualisieren. Dies ist in Situationen nützlich, wo die Variable indirekt geändert wurde, z.B. durch Übergabe ihrer Adresse via DllCall(). In diesem Modus gibt VarSetCapacity() die Länge in Bytes zurück, nicht die Kapazität.

FüllByte

Dieser Parameter wird normalerweise weggelassen, um zu verhindern, dass der Speicher der Zielvariable initialisiert wird (stattdessen wird die Variable einfach wie oben beschrieben leer gemacht). Andernfalls geben Sie eine Zahl zwischen 0 und 255 an. Jedes Byte im Speicherbereich der Zielvariable (ihre aktuelle Kapazität, die größer als GewünschteKapazität sein kann) wird auf diese Zahl gesetzt. 0 ist der am häufigsten verwendete Wert, der in Situationen nützlich ist, wo die Variable rohe Binärdaten enthalten wird, wie z.B. eine DllCall-Struktur.

Rückgabewert

Diese Funktion gibt die Anzahl der Bytes zurück, die ZielVar nun enthalten kann und größer gleich GewünschteKapazität sein wird. Wenn ZielVar keine gültige Variable ist (z.B. eine direkt geschriebene Zeichenkette oder Zahl), wird 0 zurückgegeben. Wenn das System nicht genügend Speicher hat, um die Änderung durchzuführen (sehr selten), wird ein Fehlerdialogfenster angezeigt und die aktuelle Kapazität zurückgegeben - dieses Verhalten kann sich in einer zukünftigen Version ändern.

Bemerkungen

Zusätzlich zu den in DllCall() beschriebenen Verwendungen kann diese Funktion auch verwendet werden, um die Performanz beim Zusammensetzen einer Zeichenkette durch schrittweise Verkettung zu verbessern, indem mehrfache automatische Größenanpassungen vermieden werden, wenn die endgültige Länge der Zeichenkette bereits bekannt ist. In diesem Fall muss GewünschteKapazität nicht exakt sein: Der Performanzgewinn gilt auch dann noch, wenn die Kapazität zu klein ist, außerdem beginnt die Variable sich automatisch zu erweitern, wenn die Kapazität erschöpft ist. Bei zu hoher Kapazität wird ein Teil des Speichers verschwendet, aber nur vorübergehend, da der gesamte Speicher nach der Operation mit VarSetCapacity(Var, 0) oder Var := "" wieder freigegeben werden kann.

#MaxMem begrenzt nur die automatische Erweiterung, die eine Variable selbst durchführt. Diese Direktive hat keinen Einfluss auf VarSetCapacity().

Siehe auch

DllCall(), #MaxMem, NumPut(), NumGet()

Beispiele

VarSetCapacity(MeineVar, 10240000)  ; ~10 MB
Loop
{
    ; ...
    MeineVar .= ZuVerkettendeZkette
    ; ...
}

; Erforderlichen Pufferspeicher für eine Zeichenkette berechnen.
bytes_per_char := A_IsUnicode ? 2 : 1
max_chars := 500
max_bytes := max_chars * bytes_per_char

Loop 2
{
    ; Speicher für die Verwendung mit DllCall reservieren.
    VarSetCapacity(buf, max_bytes)

    if (A_Index = 1)
        ; Variable indirekt via DllCall ändern.
        DllCall("wsprintf", "Ptr", &buf, "Str", "0x%08x", "UInt", 4919)
    else
        ; "str" verwenden, um die Länge automatisch zu aktualisieren:
        DllCall("wsprintf", "Str", buf, "Str", "0x%08x", "UInt", 4919)

    ; Verkettung, um zu zeigen, warum die Länge aktualisiert werden muss:
    wrong_str := buf . "<end>"
    wrong_len := StrLen(buf)

    ; Länge der Variable aktualisieren.
    VarSetCapacity(buf, -1)

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

    MsgBox,
    (
    Vor der Aktualisierung
      Zeichenkette: %wrong_str%
      Länge: %wrong_len%

    Nach der Aktualisierung
      Zeichenkette: %right_str%
      Länge: %right_len%
    )
}