VarSetStrCapacity

Erhöht die Speicherkapazität einer Variable oder gibt ihren Speicher frei. Normalerweise nicht erforderlich, kann aber für DllCall oder SendMessage oder zur Optimierung einer Mehrfachverkettung verwendet werden.

GewährteKapazität := VarSetStrCapacity(&ZielVar , GewünschteKapazität)

Parameter

&ZielVar

Typ: VarRef

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

GewünschteKapazität

Typ: Integer

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 Zeichen an, die die Variable nach der Anpassung enthalten soll. GewünschteKapazität ist unabhängig vom internen Nullterminator. Zum Beispiel bewirkt die Angabe von 1, dass die Variable bis zu einem Zeichen 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 VarSetStrCapacity(&Var, 0) freizugeben und dann VarSetStrCapacity(&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 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 VarSetStrCapacity(&Var, 0) den Speicher freigeben.

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 Zeichenkette indirekt geändert wurde, z.B. durch Übergabe ihrer Adresse via DllCall oder SendMessage. In diesem Modus gibt VarSetStrCapacity die Länge zurück, nicht die Kapazität.

Rückgabewert

Typ: Integer

Diese Funktion gibt die Anzahl der Zeichen zurück, die ZielVar nun enthalten kann und größer gleich GewünschteKapazität sein wird.

Misserfolg

Es wird in folgenden Fällen eine Ausnahme ausgelöst:

• ZielVar ist keine gültige Variablenreferenz. Es ist nicht möglich, eine Objekteigenschaft oder interne Variable via Referenz zu übergeben, daher ist es ungültig, diese an diese Funktion zu übergeben.
• Die gewünschte Kapazität ist zu groß, um in einen einzelnen angrenzenden Speicherblock zu passen, der dem Skript zur Verfügung steht. In seltenen Fällen kann dies daran liegen, dass dem System der Speicher ausgeht.
• GewünschteKapazität ist kleiner als -1 oder größer als die Kapazität, die die aktuelle Plattform theoretisch unterstützt.

Bemerkungen

Das Buffer-Objekt ist übersichtlicher und flexibler im Umgang mit Binärdaten, Strukturen, DllCall und ähnlichem. Zum Beispiel kann ein Buffer-Objekt einer Eigenschaft oder einem Array-Element zugewiesen werden, oder an eine Funktion übergeben oder von ihr zurückgegeben werden, ohne den Inhalt zu kopieren.

Diese Funktion kann verwendet werden, um die Performanz beim Zusammensetzen 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 VarSetStrCapacity(&Var, 0) oder Var := "" wieder freigegeben werden kann.

Siehe auch

Buffer-Objekt, DllCall, NumPut, NumGet

Beispiele

VarSetStrCapacity(&MeineVar, 5120000)  ; ~10 MB
Loop
{
    ; ...
    MeineVar .= ZuVerkettendeZkette
    ; ...
}

max_chars := 10

Loop 2
{
    ; Speicher für die Verwendung mit DllCall reservieren.
    VarSetStrCapacity(&buf, max_chars)

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

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

    ; Länge der Variable aktualisieren.
    VarSetStrCapacity(&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
    )
}