Object

In AutoHotkey ist der reguläre Objektdatentyp ein assoziatives Array, dessen Verhalten individuell angepasst werden kann. Standardmäßig unterstützen alle Objekte, die mit {}, [], Object() und Array() erstellt wurden, folgende Methoden, Eigenschaften und Funktionen.

Inhaltsverzeichnis

Methoden

InsertAt [v1.1.21+]

Fügt einen oder mehrere Werte auf einer bestimmten Position innerhalb eines linearen Arrays ein.

Object.InsertAt(Pos, Wert1 , Wert2, ... WertN)
Pos

Die Position, auf der Wert1 eingefügt werden soll. Nachfolgende Werte werden auf Pos+1, Pos+2, etc. eingefügt.

Wert1 ...

Ein oder mehrere Werte, die eingefügt werden sollen. Um einen Array mit Werten einzufügen, übergeben Sie dasArray* als letzten Parameter.

InsertAt ist das Gegenstück von RemoveAt.

Da Objekte assoziative Arrays sind, ist Pos zudem der Integer-Schlüssel, der mit Wert1 verbunden wird. Alle Elemente, die sich auf oder rechts neben Pos befinden, werden um die genaue Anzahl der Wertparameter nach rechts verschoben, sogar wenn einige davon fehlen (also wenn das Objekt ein lückenhaftes Array ist). Zum Beispiel:

x := []
x.InsertAt(1, "A", "B") ; =>  ["A", "B"]
x.InsertAt(2, "C")      ; =>  ["A", "C", "B"]

; Lückenhafte/leere Elemente bleiben erhalten:
x := ["A", , "C"]
x.InsertAt(2, "B")      ; =>  ["A", "B",    , "C"]

x := ["C"]
x.InsertAt(1, , "B")    ; =>  [   , "B", "C"]

InsertAt sollte nur verwendet werden, wenn die Integer-Schlüssel des Objekts Positionen in einem linearen Array repräsentieren. Enthält das Objekt willkürliche Integer-Schlüssel wie IDs oder Handles, wird InsertAt wahrscheinlich unerwünschte Nebenwirkungen verursachen. Zum Beispiel:

x := [], handleX := 0x4321, handleY := 0x1234
x.InsertAt(handleX, "A")
MsgBox % x[handleX]  ; A - Okay
x.InsertAt(handleY, "B")
MsgBox % x[handleX]  ; Leer
MsgBox % x[handleX+1]  ; Dies ist die neue "Position" von "A"

InsertAt hat keinen Effekt auf Zeichenketten- oder Objektschlüssel, demzufolge kann es ohne Probleme bei Objekten mit unterschiedlichen Schlüsseltypen verwenden werden.

RemoveAt [v1.1.21+]

Entfernt Elemente auf der angegebenen Position in einem linearen Array.

Object.RemoveAt(Pos , Länge)
Pos

Die Position des Wertes oder der Werte, die entfernt werden sollen.

Länge

Die Länge des Wertebereichs, der entfernt werden soll. Elemente von Pos bis Pos+Länge-1 werden entfernt. Lässt man diesen Parameter weg, wird nur ein Element entfernt.

Lässt man Länge weg, wird der auf Pos entfernte Wert zurückgegeben (leer, wenn keine entfernt wurden). Ansonsten ist der Rückgabewert die Anzahl der entfernten Elemente, die Werte enthielten. Die Anzahl und Länge können bei einem lückenhaften Array unterschiedlich sein, aber sie geht immer von 0 bis Länge.

RemoveAt ist das Gegenstück der InsertAt.

Die restlichen Elemente auf der rechten Seite von Pos werden um den via Länge definierten Wert (oder standardmäßig um 1) nach links verschoben, selbst wenn einige Elemente im entfernten Bereich keine Werte haben. Zum Beispiel:

x := ["A", "B"]
MsgBox % x.RemoveAt(1)  ; A
MsgBox % x[1]           ; B

x := ["A", , "C"]
MsgBox % x.RemoveAt(1, 2)  ; 1
MsgBox % x[1]              ; C

RemoveAt sollte nur verwendet werden, wenn die Integer-Schlüssel des Objekts Positionen in einem linearen Array repräsentieren. Enthält das Objekt willkürliche Integer-Schlüssel wie IDs oder Handles, wird RemoveAt wahrscheinlich unerwünschte Nebenwirkungen verursachen. Zum Beispiel:

x := {0x4321: "A", 0x1234: "B"}
MsgBox % x.RemoveAt(0x1234) ; B
MsgBox % x[0x4321]          ; Leer
MsgBox % x[0x4321-1]        ; A

RemoveAt hat keinen Effekt auf Zeichenketten- oder Objektschlüssel, demzufolge kann es ohne Probleme bei Objekten mit unterschiedlichen Schlüsseltypen verwenden werden.

Push [v1.1.21+]

Fügt Werte an das Ende eines Arrays an.

Object.Push( Wert, Wert2, ..., WertN )
Wert ...

Ein oder mehrere Werte, die eingefügt werden sollen. Um einen Array mit Werten einzufügen, übergeben Sie dasArray* als letzten Parameter.

Der Rückgabewert ist die Position des zuletzt eingefügten Wertes. Kann negativ sein, wenn das Array nur Elemente bei negativen Indexen enthält.

Der erste Wert wird auf Position 1 eingefügt, wenn das Array leer ist oder nur Zeichenketten- oder Objektschlüssel enthält.

Ansonsten wird der erste Wert auf Object.MaxIndex() + 1 eingefügt, selbst wenn diese Position negativ oder null ist. Alternativ kann man, wenn das unerwünscht ist, besonders bei einem Objekt mit negativen Schlüsseln, Object.InsertAt(Object.Length() + 1, ...) benutzen.

Pop [v1.1.21+]

Entfernt und gibt das letzte Array-Element zurück.

Wert := Object.Pop()

Wenn es keine Array-Elemente gibt, ist der Rückgabewert eine leere Zeichenkette. Ansonsten ist es das gleiche wie:

Wert := Object.RemoveAt(Object.Length())

Delete [v1.1.21+]

Entfernt Schlüssel-Wert-Paare aus einem Objekt.

Object.Delete(Schlüssel)
Object.Delete(ErsterSchlüssel, LetzterSchlüssel)
Schlüssel

Beliebiger einzelner Schlüssel.

ErsterSchlüssel, LetzterSchlüssel

Ein gültiger Bereich mit Integer- oder Zeichenkettenschlüsseln, wo ErsterSchlüssel <= LetzterSchlüssel gilt. Beide Schlüssel müssen vom gleichen Typ sein.

Bei nur einem Parameter wird der entfernte Wert zurückgegeben (leer, wenn es keinen gibt). Ansonsten ist der Rückgabewert die Anzahl der Schlüssel, die gefunden und entfernt wurden.

Im Gegensatz zu RemoveAt hat Delete keine Auswirkung auf Schlüssel-Wert-Paare, die es nicht entfernt. Zum Beispiel:

x := ["A", "B"]
MsgBox % x.RemoveAt(1)  ; A
MsgBox % x[1]           ; B

x := ["A", "B"]
MsgBox % x.Delete(1)    ; A
MsgBox % x[1]           ; Leer

MinIndex / MaxIndex [AHK_L 31+]

Gibt den niedrigsten oder höchsten Integer-Schlüssel zurück, sofern vorhanden.

MinIndex := Object.MinIndex()
MaxIndex := Object.MaxIndex()

Wenn keine Schlüssel vorhanden sind, wird eine leere Zeichenkette zurückgegeben.

Length [v1.1.21+]

Gibt die Länge eines linearen Arrays zurück.

Länge := Object.Length()

Diese Methode gibt die Länge eines linearen Arrays zurück, beginnend bei Position 1; also entweder der höchste positive Integer-Schlüssel innerhalb des Objekts, oder 0, wenn keine vorhanden sind.

MsgBox % ["A", "B", "C"].Length()  ;  3
MsgBox % ["A",    , "C"].Length()  ;  3
MsgBox % {-10: 0, 10: 0}.Length()  ; 10
MsgBox % {-10: 0, -1: 0}.Length()  ;  0

Count [v1.1.29+]

Gibt die Anzahl der Schlüssel-Wert-Paare zurück, die in einem Objekt vorhanden sind.

Anzahl := Object.Count()

Beispiele:

MsgBox % {A: 1, Z: 26}.Count()    ;  2
MsgBox % ["A", "B", "C"].Count()  ;  3
MsgBox % ["A",    , "C"].Count()  ;  2

SetCapacity [AHK_L 31+]

Passt die Kapazität eines Objekts oder eines seiner Felder an.

Object.SetCapacity(MaxElemente)
Object.SetCapacity(Schlüssel, ByteGröße)
MaxElemente

Die maximale Anzahl an Schlüssel-Wert-Paaren, die das Objekt beinhalten soll, bevor es automatisch erweitert werden muss. Ist dieser Parameter kleiner als die aktuelle Anzahl an Schlüssel-Wert-Paaren, wird stattdessen dieser Wert verwendet und ungenutzter Speicher freigegeben.

Schlüssel

Beliebiger gültiger Schlüssel.

ByteGröße

Die neue Größe in Bytes für den Zeichenkettenpuffer des Feldes, ohne den Null-Terminator. Wenn das Feld nicht vorhanden ist, wird es erstellt. Wenn ByteGröße 0 ist, wird der Pufferspeicher freigegeben, aber das leere Feld nicht entfernt. Wenn ByteGröße kleiner als die aktuelle Größe ist, werden überschüssige Daten gekürzt; ansonsten werden alle vorhandenen Daten beibehalten.

Der Rückgabewert ist bei Erfolg die neue Kapazität, ansonsten eine leere Zeichenkette.

GetCapacity [AHK_L 31+]

Gibt die Kapazität eines Objekts oder eines seiner Felder zurück.

MaxElemente := Object.GetCapacity()
ByteGröße := Object.GetCapacity(Schlüssel)

Wenn das Feld nicht vorhanden ist oder keine Zeichenkette enthält, wird eine leere Zeichenkette zurückgegeben.

GetAddress [AHK_L 31+]

Gibt die aktuelle Adresse des Zeichenketten-Puffers eines Feldes zurück, wenn es einen hat.

Ptr := Object.GetAddress(Schlüssel)

NewEnum [AHK_L 49+]

Gibt einen neuen Enumerator zurück, um Schlüssel-Wert-Paare eines Objekts zu enumerieren.

Enum := Object._NewEnum()

Diese Methode wird in der Regel nicht direkt, sondern über die For-Schleife aufgerufen.

HasKey [AHK_L 53+]

Gibt True zurück, wenn der angegebene Schlüssel mit einem Wert (auch "") innerhalb eines Objekts verbunden ist, ansonsten False.

Object.HasKey(Schlüssel)

Clone [AHK_L 60+]

Gibt eine flache Kopie eines Objekts zurück.

Klon := Object.Clone()

Insert [AHK_L 31+]

Veraltet: Insert ist nicht für neue Skripte empfohlen. Verwenden Sie stattdessen InsertAt, Push, ObjRawSet oder eine einfache Zuweisung.

Fügt Schlüssel-Wert-Paare in das Objekt ein, und passt vorhandene Schlüssel automatisch an, wenn ein Integer-Schlüssel angegeben ist.

Object.Insert(Pos, Wert1 , Wert2, ... WertN )
Object.Insert(Wert)
Object.Insert(ZketteOderObjektSchlüssel, Wert)

Das Verhalten von Insert hängt davon ab, wie viele Parameter vorhanden sind und von welchem Typ sie sind:

Insert gibt True zurück. In [v1.1.21] und höher wird eine Ausnahme ausgelöst, wenn eine Speicherreservierung fehlschlägt. Ältere Versionen gaben in diesem Fall eine leere Zeichenkette zurück.

Remove [AHK_L 31+]

Veraltet: Remove ist nicht für neue Skripte empfohlen. Verwenden Sie stattdessen RemoveAt, Delete oder Pop.

Entfernt Schlüssel-Wert-Paare aus einem Objekt.

Object.Remove(ErsterSchlüssel, LetzterSchlüssel)

Das Verhalten von Remove hängt davon ab, wie viele Parameter vorhanden sind und von welchem Typ sie sind:

Eigenschaften

Base

Ermittelt oder setzt das Base-Objekt eines Objekts.

BaseObject := Object.Base
Object.Base := BaseObject

BaseObject muss ein Objekt oder eine leere Zeichenkette sein.

Eigenschaften und Methoden, die via Base-Objekt definiert werden, sind nur zugänglich, während dieses Base-Objekt in Gebrauch ist. Ändert man also das Base von Object, würde man gleichzeitig auch die Auswahl an verfügbaren Eigenschaften und Methoden ändern.

Siehe auch: ObjGetBase(), ObjSetBase()

Funktionen

ObjRawGet [v1.1.29+]

Ermittelt den Wert, der einem bestimmten Schlüssel innerhalb eines Objekts zugeordnet ist.

Wert := ObjRawGet(Object, Schlüssel)

Wenn Object den Schlüssel nicht enthält, ist der Rückgabewert eine leere Zeichenkette. Es werden keine Metafunktionen oder Eigenschaftsfunktionen aufgerufen. Die Inhalte der Base-Objekte von Object werden nicht berücksichtigt, und da base selbst standardmäßig eine Eigenschaft und kein Schlüssel-Wert-Paar ist, wird es normalerweise nicht zurückgegeben.

Es wird eine Ausnahme ausgelöst, wenn Object vom falschen Typ ist.

ObjRawSet [v1.1.21+]

Speichert oder überschreibt ein Schlüssel-Wert-Paar in einem Objekt.

ObjRawSet(Object, Schlüssel, Wert)

Diese Funktion wurde bereitgestellt, um den Skripten die Möglichkeit zu bieten, die __Set-Metafunktion und Eigenschaften zu umgehen. Falls dies nicht notwendig ist, sollte stattdessen eine normale Zuweisung verwendet werden. Zum Beispiel: Object[Schlüssel] := Wert

Da der Zweck darin besteht, Metafunktionen zu umgehen, ist dies nur eine Funktion, keine Methode. Das Aufrufen einer internen Methode ruft generell auch die __Call-Metafunktion auf.

Es wird eine Ausnahme ausgelöst, wenn Object vom falschen Typ ist.

ObjGetBase [v1.1.29+]

Gibt das Base-Objekt eines Objekts zurück.

BaseObject := ObjGetBase(Object)

Es werden keine Metafunktionen aufgerufen. Das base des Objekts wird auch dann zurückgegeben, wenn der Schlüssel "base" in das Objekt gespeichert worden ist (z. B. mit ObjRawSet oder SetCapacity). Es wird eine leere Zeichenkette zurückgegeben, wenn das Objekt kein base hat.

Es wird eine Ausnahme ausgelöst, wenn Object vom falschen Typ ist.

Siehe auch: Base-Eigenschaft

ObjSetBase [v1.1.29+]

Setzt das Base-Objekt eines Objekts.

ObjSetBase(Object, BaseObject)

Es werden keine Metafunktionen aufgerufen. Das base des Objekts wird auch dann gesetzt, wenn der Schlüssel "base" in das Objekt gespeichert worden ist (z. B. mit ObjRawSet oder SetCapacity). Es wird eine leere Zeichenkette zurückgegeben, wenn das Objekt kein base hat.

Es wird eine Ausnahme ausgelöst, wenn Object vom falschen Typ ist oder wenn BaseObject kein Objekt oder eine leere Zeichenkette ist.

Siehe auch: Base-Eigenschaft

Bemerkungen

Jede Methode hat außerdem eine äquivalente Funktion, mit der jedes benutzerdefinierte Verhalten, das vom Objekt implementiert wurde, umgangen werden kann. Diese Funktionen sollten nur für diesen Zweck verwendet werden. Um eine derartige Funktion aufzurufen, fügen Sie "Obj" vor dem Methodennamen an und übergeben Sie das Zielobjekt als ersten Parameter. Zum Beispiel:

array := [1, 2, 3]
MsgBox % ObjMaxIndex(array) " = " array.MaxIndex()

Wenn eine Obj-Methode mit einem Objekt oder Wert falschen Typs aufgerufen wird, gibt sie eine leere Zeichenkette zurück. Eigenständige Funktionen wie ObjRawSet lösen eine Ausnahme aus.