Object

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

Methoden:

Eigenschaften:

Funktionen:

Veraltet (sollte nicht mehr verwendet werden):

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 so eine Funktion aufzurufen, fügt man vor dem Methodennamen "Obj" an und übergibt 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.

 

InsertAt [v1.1.21+]

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

Object.InsertAt(Pos, Value1 , Value2, ... ValueN)
Pos

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

Value1 ...

Eine oder mehrere Werte, die eingefügt werden sollen. Um einen Array mit Werten einzufügen, übergibt man dasArray* als letzten Parameter.

Bemerkungen

InsertAt ist das Gegenstück von RemoveAt.

Da Objekte assoziative Arrays sind, ist Pos zudem der Integer-Key, der mit Value1 verbunden wird. Alle Elemente, die sich auf oder rechts neben Pos befinden, werden in Abhängigkeit der exakten Value-Parameteranzahl 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-Keys des Objekts Positionen in einem linearen Array repräsentieren. Enthält das Objekt willkürliche Integer-Keys 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 Objekt-Keys, demzufolge kann es ohne Probleme bei Objekten mit unterschiedlichen Key-Typen 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. Fehlt dieser Parameter, wird nur ein Element entfernt.

Rückgabewert

Fehlt Länge, wird der entfernte Wert auf Pos 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.

Bemerkungen

RemoveAt ist das Gegenstück der InsertAt.

Die restlichen Elemente auf der rechten Seite von Pos werden in Abhängigkeit der Länge (oder um 1, wenn sie fehlt) 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-Keys des Objekts Positionen in einem linearen Array repräsentieren. Enthält das Objekt willkürliche Integer-Keys 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 Objekt-Keys, demzufolge kann es ohne Probleme bei Objekten mit unterschiedlichen Key-Typen verwenden werden.

Push [v1.1.21+]

Fügt Values an das Ende eines Arrays an.

Object.Push( Value, Value2, ..., ValueN )
Value ...

Eine oder mehrere Werte, die eingefügt werden sollen. Um einen Array mit Werten einzufügen, übergibt man dasArray* als letzten Parameter.

Rückgabewert

Die Position des zuletzt eingefügten Wertes. Kann negativ sein, wenn das Array nur Elemente bei negativen Indexen enthält.

Bemerkungen

Der erste Wert wird auf Position 1 eingefügt, wenn das Array leer ist oder nur Zeichenketten- oder Objekt-Keys 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 Keys, Object.InsertAt(Object.Length() + 1, ...) benutzen.

Pop [v1.1.21+]

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

Value := Object.Pop()

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

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

Delete [v1.1.21+]

Entfernt Key-Value-Paare von einem Objekt.

Object.Delete(Key)
Object.Delete(ErsterKey, LetzterKey)
Key

Beliebiger einzelner Key.

ErsterKey, LetzterKey

Ein gültiger Bereich von Integer- oder Zeichenketten-Keys, wo ErsterKey <= LetzterKey gilt. Beide Keys müssen vom gleichen Typ sein.

Rückgabewert

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

Bemerkungen

Im Gegensatz zu RemoveAt hat Delete keine Auswirkung auf Key-Value-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+]

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

Sofern Integer-Keys vorhanden sind, gibt MinIndex den niedrigsten und MaxIndex den höchsten Key zurück. Ansonsten wird eine leere Zeichenkette zurückgegeben.

Length [v1.1.21+]

Länge := Object.Length()

Gibt die Länge eines linearen Arrays zurück, beginnend bei Position 1; also entweder der höchste positive Integer-Key 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+]

Anzahl := Object.Count()

Gibt die Anzahl der im Objekt vorhandenen Key-Value-Paare zurück.

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(Key, Bytegröße)
MaxElemente

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

Key

Beliebiger gültiger Key.

Bytegröße

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

Rückgabe

Bei Erfolg die neue Kapazität, ansonsten eine leere Zeichenkette.

GetCapacity [AHK_L 31+]

MaxElemente := Object.GetCapacity()
Bytegröße := Object.GetCapacity(Key)

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

Gibt eine leere Zeichenkette zurück, wenn das Feld nicht existiert oder keine Zeichenkette enthält.

GetAddress [AHK_L 31+]

Ptr := Object.GetAddress(Key)

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

NewEnum [AHK_L 49+]

Enum := Object._NewEnum()

Gibt einen neuen Enumerator zurück, um Key-Value-Paare des Objekts zu enumerieren. Diese Methode wird in der Regel nicht direkt, sondern über die For-Schleife aufgerufen.

HasKey [AHK_L 53+]

Object.HasKey(Key)

Gibt wahr zurück, wenn Key mit einem Value (auch "") innerhalb des Objekts verbunden ist, ansonsten falsch.

Clone [AHK_L 60+]

Klon := Object.Clone()

Gibt eine flache Kopie des Objekts zurück.

Base

Ermittelt oder setzt das Base-Objekt des 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 Object's base, würde man gleichzeitig auch die Auswahl an verfügbaren Eigenschaften und Methoden ändern.

Siehe auch: ObjGetBase, ObjSetBase

ObjRawGet [v1.1.29+]

Ermittelt den Wert, der einem bestimmten Key innerhalb von Object zugeordnet ist.

Value := ObjRawGet(Object, Key)

Wenn Object den Key nicht enthält, ist der Rückgabewert eine leere Zeichenkette. Es werden keine Meta-Funktionen oder Eigenschaftsfunktionen aufgerufen. Die Inhalte der Base-Objekte von Object werden nicht berücksichtigt. Da base selbst standardmäßig kein Key-Value-Paar sondern eine Eigenschaft 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 Key-Value-Paar im Objekt.

ObjRawSet(Object, Key, Value)

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

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

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

ObjGetBase [v1.1.29+]

Gibt das Base-Objekt des Objekts zurück.

BaseObject := ObjGetBase(Object)

Es werden keine Meta-Funktionen aufgerufen. Das base des Objekts wird auch dann zurückgegeben, wenn der Key "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 des Objekts.

ObjSetBase(Object, BaseObject)

Es werden keine Meta-Funktionen aufgerufen. Das base des Objekts wird auch dann gesetzt, wenn der Key "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

Insert [AHK_L 31+]

Veraltet: Insert ist nicht bei neuen Skripten empfohlen. Verwenden Sie stattdessen InsertAt, Push, ObjRawSet oder eine einfache Zuweisung.

Fügt Key-Value-Paare in das Objekt ein, und passt vorhandene Keys automatisch an, wenn ein Integer-Key angegeben ist.

Object.Insert(Pos, Value1 , Value2, ... ValueN )
Object.Insert(Value)
Object.Insert(ZeichenketteOderObjektKey, Value)

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 Speicherzuweisung fehlschlägt. Ältere Versionen gaben in diesem Fall eine leere Zeichenkette zurück.

Remove [AHK_L 31+]

Veraltet: Remove ist nicht bei neuen Skripten empfohlen. Verwenden Sie stattdessen RemoveAt, Delete oder Pop.

Entfernt Key-Value-Paare von einem Objekt.

Object.Remove(ErsterKey, LetzterKey)

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