class Map extends Object
Ein Map-Objekt ordnet einen Satz von Werten, Schlüssel genannt, einem anderen Satz von Werten zu. Ein Schlüssel und der Wert, dem er zugeordnet ist, werden als Schlüssel-Wert-Paar bezeichnet. Ein Map-Objekt kann beliebig viele Schlüssel-Wert-Paare enthalten, aber jeder Schlüssel muss eindeutig sein.
Ein Schlüssel kann ein Integer, eine Objektreferenz oder eine nullterminierte Zeichenkette sein. Der Vergleich von Zeichenkettenschlüsseln erfolgt Groß-/Kleinschreibung-sensitiv, während Objekte via Referenz/Adresse verglichen werden. Float-Schlüssel werden automatisch in eine Zeichenkette umgewandelt.
Die einfachste Verwendung eines Map-Objekts besteht darin, ein Schlüssel-Wert-Paar über die implizite __Item-Eigenschaft abzurufen oder zu setzen, indem man einfach den Schlüssel in eckigen Klammern hinter das Map-Objekt schreibt. Zum Beispiel:
Farben := Map()
Farben["Rot"] := "ff0000"
Farben["Grün"] := "00ff00"
Farben["Blau"] := "0000ff"
for Farbe in Array("Blau", "Grün")
MsgBox Farben[Farbe]
"MapObj" wird hier stellvertretend für ein beliebiges Map-Objekt verwendet, da "Map" die Klasse selbst ist.
Zusätzlich zu den von Object geerbten Methoden und Eigenschaften haben Map-Objekte die folgenden vordefinierten Methoden und Eigenschaften.
Erstellt ein Map-Objekt und setzt Elemente.
MapObj := Map(Schlüssel1, Wert1, Schlüssel2, Wert2, ...)
MapObj := Map.Call(Schlüssel1, Wert1, Schlüssel2, Wert2, ...)
Dies ist dasselbe wie, als würde man jedes Element mit MapObj[Schlüssel] := Wert setzen, außer dass __Item nicht aufgerufen wird und Capacity automatisch angepasst wird, um zu vermeiden, dass es während eines einzigen Aufrufs mehrfach erweitert wird.
Parameter sind durch __New definiert.
Entfernt alle Schlüssel-Wert-Paare aus einem Map-Objekt.
MapObj.Clear()
Gibt eine flache Kopie eines Map-Objekts zurück.
Klon := MapObj.Clone()
Alle Schlüssel-Wert-Paare werden in das neue Map-Objekt kopiert. Objektreferenzen werden kopiert (wie bei einer normalen Zuweisung), nicht die Objekte selbst.
Eigene Eigenschaften, eigene Methoden und Basis werden wie bei Obj.Clone kopiert.
Entfernt ein Schlüssel-Wert-Paar aus einem Map-Objekt.
EntfernterWert := MapObj.Delete(Schlüssel)
Typ: Integer, Objekt oder Zeichenkette
Ein beliebiger Schlüssel. Wenn das Map-Objekt diesen Schlüssel nicht enthält, wird ein UnsetItemError ausgelöst.
Typ: Beliebig
Diese Methode gibt den entfernten Wert zurück.
Gibt den Wert eines bestimmten Schlüssels oder einen Standardwert zurück.
Wert := MapObj.Get(Schlüssel , Standardwert)
Diese Methode bewirkt folgendes:
MapObj.Default zurückgeben, falls definiert.Wenn Standardwert weggelassen wird, ist dies äquivalent zu MapObj[Schlüssel], außer dass __Item nicht aufgerufen wird.
Gibt 1 (true) zurück, wenn der angegebene Schlüssel einen Wert in einem Map-Objekt hat, andernfalls 0 (false).
MapObj.Has(Schlüssel)
Setzt beliebig viele Elemente.
MapObj.Set(Schlüssel, Wert, Schlüssel2, Wert2, ...)
Dies ist dasselbe wie, als würde man jedes Element mit MapObj[Schlüssel] := Wert setzen, außer dass __Item nicht aufgerufen wird und Capacity automatisch angepasst wird, um zu vermeiden, dass es während eines einzigen Aufrufs mehrfach erweitert wird.
Typ: Objekt
Diese Methode gibt das Map zurück.
Enumeriert Schlüssel-Wert-Paare.
For Schlüssel , Wert in MapObj
Gibt einen neuen Enumerator zurück. Diese Methode wird typischerweise nicht direkt aufgerufen. Stattdessen wird das Map-Objekt direkt an eine For-Schleife übergeben, die __Enum einmal aufruft und dann den Enumerator pro Schleifenwiederholung einmal aufruft. Jeder Aufruf des Enumerators gibt den nächsten Schlüssel und/oder Wert zurück. Die Variablen der For-Schleife entsprechen den folgenden Parametern des Enumerators:
Typ: Integer, Objekt oder Zeichenkette
Der Schlüssel.
Typ: Beliebig
Der Wert.
Setzt Elemente. Äquivalent zu Set.
MapObj.__New(Schlüssel, Wert, Schlüssel2, Wert2, ...)
Diese Methode existiert zur Unterstützung von Call und ist nicht für den direkten Aufruf gedacht. Siehe Konstruktion und Destruktion.
Ruft die Anzahl der Schlüssel-Wert-Paare in einem Map-Objekt ab.
Anzahl := MapObj.Count
Ermittelt oder setzt die aktuelle Kapazität eines Map-Objekts.
MaxElemente := MapObj.Capacity
MapObj.Capacity := MaxElemente
MaxElemente ist ein Integer, der die maximale Anzahl von Schlüssel-Wert-Paaren repräsentiert, die das Map-Objekt enthalten kann, bevor es automatisch erweitert werden muss. Wenn ein Wert kleiner als die aktuelle Anzahl von Schlüssel-Wert-Paaren gesetzt wird, wird stattdessen diese Anzahl verwendet und ungenutzter Speicher freigegeben.
Ermittelt oder setzt die Groß-/Kleinschreibung-Sensitivität eines Map-Objekts.
AktuelleEinstellung := MapObj.CaseSense
MapObj.CaseSense := NeueEinstellung
AktuelleEinstellung ist NeueEinstellung, falls zugewiesen, andernfalls standardmäßig On (aber beachten Sie, dass diese Eigenschaft nur die Zeichenkettenvariante der aktuellen Einstellung abruft).
NeueEinstellung ist eine(r) der folgenden Zeichenketten oder Integer (boolesch):
On oder 1 (true): Die Suche nach Schlüsseln erfolgt Groß-/Kleinschreibung-sensitiv. Standardeinstellung.
Off oder 0 (false): Die Suche nach Schlüsseln erfolgt nicht Groß-/Kleinschreibung-sensitiv, d.h. die Großbuchstaben A bis Z und die entsprechenden Kleinbuchstaben werden als identisch betrachtet.
Locale: Die Suche nach Schlüsseln erfolgt nicht Groß-/Kleinschreibung-sensitiv, gemäß den Regeln der aktuellen Sprach- und Regionseinstellungen des Benutzers. Zum Beispiel behandeln die meisten englischen und westeuropäischen Sprach- und Regionseinstellungen die Großbuchstaben A bis Z, einschließlich ASCII-fremde Großbuchstaben wie Ä und Ü, und die entsprechenden Kleinbuchstaben als identisch. Locale ist 1- bis 8-mal langsamer als Off, abhängig von den zu vergleichenden Zeichenketten.
Wenn das Map-Objekt nicht leer ist und dieser Eigenschaft etwas zugewiesen wird, wird eine Ausnahme ausgelöst.
Definiert den Standardwert, der zurückgegeben wird, wenn ein Schlüssel nicht gefunden wird.
MapObj.Default := Wert
Diese Eigenschaft ist standardmäßig nicht vorhanden, kann aber via Skript definiert werden. Wenn definiert, wird ihr Wert durch __Item oder Get zurückgegeben, wenn das angeforderte Element nicht gefunden werden kann, anstatt einen UnsetItemError auszulösen. Die Eigenschaft kann mit den üblichen Mitteln implementiert werden, einschließlich einer dynamischen Eigenschaft oder einer Metafunktion, aber um festzustellen, welcher Schlüssel abgefragt wurde, müsste stattdessen __Item oder Get überschrieben werden.
Ermittelt oder setzt den Wert eines Schlüssel-Wert-Paares.
Wert := MapObj[Schlüssel]
Wert := MapObj.__Item[Schlüssel]
MapObj[Schlüssel] := Wert
MapObj.__Item[Schlüssel] := Wert
Beim Abrufen eines Wertes muss Schlüssel ein eindeutiger Wert sein, der zuvor einem anderen Wert zugeordnet wurde. Es wird ein UnsetItemError ausgelöst, wenn Schlüssel keinen zugeordneten Wert im Map-Objekt hat, es sei denn, es ist eine Default-Eigenschaft definiert, dann wird deren Wert zurückgegeben.
Beim Zuweisen eines Wertes kann Schlüssel ein beliebiger Wert sein, der mit Wert assoziiert werden kann, d.h. der Schlüssel wird verwendet, um später auf Wert zugreifen zu können. Float-Schlüssel werden automatisch in eine Zeichenkette umgewandelt.
Der Eigenschaftsname __Item wird typischerweise weggelassen, wie oben gezeigt, ist aber nützlich, um die Eigenschaft zu überschreiben.