StrPut

Kopiert eine Zeichenkette auf eine Speicheradresse oder in einen Puffer (optional mit Codepage-Umwandlung).

GeschriebeneBytes := StrPut(Zkette, Ziel , Länge, Kodierung)
GeschriebeneBytes := StrPut(Zkette, Ziel , Kodierung)
NotwPufGröße      := StrPut(Zkette , Kodierung)

Parameter

Zkette

Typ: Zeichenkette

Eine beliebige Zeichenkette. Wenn eine Zahl angegeben ist, wird diese automatisch in eine Zeichenkette umgewandelt.

Zkette wird standardmäßig in der nativen Kodierung vermutet.

Ziel

Typ: Objekt oder Integer

Ein Buffer-ähnliches Objekt oder eine Speicheradresse, in die die Zeichenkette geschrieben werden soll.

Es kann ein beliebiges Objekt mit einer Ptr- und Size-Eigenschaft verwendet werden, aber diese Funktion ist für das native Buffer-Objekt optimiert. Die Übergabe eines Objekts mit diesen Eigenschaften stellt sicher, dass die Funktion keinen Speicher in einen ungültigen Bereich schreibt, was zu Abstürzen oder anderem unvorhersehbaren Verhalten führen kann.

Hinweis: Bei einer Codepage-Umwandlung kann die erforderliche Puffergröße von der Größe der Quellzeichenkette abweichen. Rufen Sie in solchen Fällen StrPut mit zwei Parametern auf, um die erforderliche Größe zu berechnen.

Länge

Typ: Integer

Die maximale Anzahl der zu schreibenden Zeichen, einschließlich des Nullterminators, falls erforderlich.

Wenn Länge 0 oder kleiner als die voraussichtliche Länge nach der Umwandlung ist (oder kleiner als die Länge der Quellzeichenkette ohne Umwandlung ist), wird eine Ausnahme ausgelöst.

Länge darf nicht weggelassen werden, wenn Ziel eine reine Speicheradresse ist, es sei denn, es ist bekannt, dass die Puffergröße ausreicht, z.B. wenn der Pufferspeicher auf Basis eines früheren StrPut-Aufrufs mit derselben Zkette und Kodierung reserviert wurde.

Wenn Ziel ein Objekt ist, wird die Angabe einer Länge, die die Puffergröße (berechnet aus Ziel.Size) überschreitet, als Fehler gewertet, selbst wenn die umgewandelte Zeichenkette in den Pufferspeicher passen würde.

Hinweis: Wenn Kodierung angegeben ist, muss Länge die Größe des Pufferspeichers (in Zeichen) sein, nicht die Länge von Zkette oder einer Teilzeichenkette, da die Umwandlung deren Länge erhöhen kann.

Hinweis: Länge wird in Zeichen gemessen, während Puffergrößen normalerweise in Bytes gemessen werden, ebenso wie der Rückgabewert von StrPut. Um die Puffergröße in Bytes anzugeben, verwenden Sie ein Buffer-ähnliches Objekt im Ziel-Parameter.

Kodierung

Typ: Zeichenkette oder Integer

Wenn weggelassen, wird die Zeichenkette einfach kopiert oder gemessen, ohne dass eine Umwandlung stattfindet. Andernfalls geben Sie die Zielkodierung an, z.B. "UTF-8", "UTF-16" oder "CP936". Für numerische Identifikatoren kann das Präfix "CP" nur im 4-Parameter-Modus weggelassen werden. Geben Sie eine leere Zeichenkette oder "CP0" an, um die Standard-ANSI-Codepage des Systems zu verwenden.

Rückgabewert

Typ: Integer

Im 4- oder 3-Parameter-Modus gibt diese Funktion die Anzahl der geschriebenen Bytes zurück. Ein Nullterminator wird nur dann geschrieben und zum Rückgabewert hinzugefügt, wenn genügend Platz vorhanden ist, d.h. er wird weggelassen, wenn Länge oder Ziel.Size (multipliziert mit der Größe eines Zeichens) exakt mit der Länge der umgewandelten Zeichenkette übereinstimmt.

Im 2-Parameter-Modus gibt diese Funktion die erforderliche Puffergröße in Bytes zurück, inklusive Platz für den Nullterminator.

Fehlerbehandlung

Es wird ein ValueError ausgelöst, wenn ungültige Parameter erkannt wurden, z.B. wenn die umgewandelte Zeichenkette länger als Länge oder Ziel.Size ist.

Es wird ein OSError ausgelöst, wenn die Umwandlung nicht durchgeführt werden konnte.

Bemerkungen

Beachten Sie, dass für den Zkette-Parameter immer die native Kodierung der aktuellen EXE-Datei von AutoHotkey vermutet wird, während Kodierung die Kodierung der Zeichenkette angibt, die in das angegebene Ziel geschrieben wird. Wenn keine Kodierung angegeben ist, wird die Zeichenkette einfach kopiert oder gemessen, ohne dass eine Umwandlung stattfindet.

Siehe auch

Zeichenkettenkodierung, StrGet, Binärkompatibilität, FileEncoding, DllCall, Buffer-Objekt, VarSetStrCapacity

Beispiele

StrPut(Zkette, Adresse, "cp0")  ; Codepage 0, unbestimmte Puffergröße
StrPut(Zkette, Adresse, n, 0)   ; Maximal n Zeichen, Codepage 0
StrPut(Zkette, Adresse, 0)      ; Nicht unterstützt (maximal 0 Zeichen)

; Gibt ein Buffer-Objekt zurück, das die Zeichenkette enthält:
StrBuf(Zkette, Kodierung)
{
    ; Erforderliche Größe berechnen und Pufferspeicher reservieren.
    buf := Buffer(StrPut(Zkette, Kodierung))
    ; Die Zeichenkette kopieren oder umwandeln.
    StrPut(Zkette, buf, Kodierung)
    return buf
}