map_var	Die Funktion m$find3 erwartetet (wie alle m$*() Funktionen) als ersten Parameter eine Referenz auf eine (ggf. indizierte) Variable. Diese Variable wird identisch zu map() zwangsweise in eine Map gewandelt, um anschließend modifiziert zu werden. Der Inhalt der Variable map_var wird nicht auf den Stack kopiert. Stattdessen wird direkt und damit effizient auf den Inhalt der Variable zugegriffen.
search	Schlüssel, unter dem die Elemente gesucht werden sollen. Dieser Parameter wird zwangsweise mittels string() in eine Zeichenkette gewandelt.

Beschreibung:

Es wird das Element mit dem Schlüssel search sowie die nächsten Nachbarn gesucht.

Beispiele
Ausdruck	Ergebnis
m1	@MAP
m$find3(m1,'x')	@LIST#4[0,,,]
m2	@MAP#3["b"=1,"d"=2,"f"=2]
m$find3(m2,'a')	@LIST#4[2,,,"b"]
m$find3(m2,'b')	@LIST#4[1,,"b","d"]
m$find3(m2,'c')	@LIST#4[3,"b",,"d"]
m$find3(m2,'d')	@LIST#4[1,"b","d","f"]
m$find3(m2,'e')	@LIST#4[3,"d",,"f"]
m$find3(m2,'f')	@LIST#4[1,"d","f",]
m$find3(m2,'g')	@LIST#4[4,"f",,]

Die alternative Funktion m$find2() arbeitet ähnlich und liefert zwei Schlüssel als Funktionsergebnis.

Funktionsergebnis: LIST

Als Funktionsergebnis wird eine Liste mit vier Einträgen geliefert. Der erste Eintrag (Index 0) enthält einen Status (siehe folgende Aufzählung). Die drei folgenden Einträge in der Liste (Index 1 (prev), 2 (id) und 3 (next)) geben die Schlüssel der gefundenen Elemente an.

_FIND_EMPTY_MAP := 0
Es existiert kein Element in der Map. Die drei Schlüssel enthalten jeweils den Wert NONE.
_FIND_FOUND := 1
Es existiert ein Element mit dem Schlüssel search. Das Element mit dem Index 2 enthält dieses Schlüssel als Zeichenkette. Die beiden Elemente mit den Indizes 1 und 3 anthalten die Schlüssel des Vorgängers bzw. Nachfolgers, oder $NONE, falls Vorgänger bzw. Nachfolger nicht existieren.
_FIND_BEFORE := 2
Es existiert kein Element mit dem Schlüssel search. Alle Element der Map haben einen größeren Schlüssel als search. Die Elemente mit dem Index 1 und 2 sind NONE und das Element mit dem Index 3 enthält als Zeichenkette den Schlüssel des ersten Elementes der Map.
_FIND_BETWEEN := 3
Es existiert kein Element mit dem Schlüssel search. search liegt irgendwo zwischen dem ersten und dem letzten Element der Map. Das Element mit dem Index 1 enthält als Zeichenkette den Schlüssel des nächst kleineren Elementes und das Element mit dem Index 3 den Schlüssel des nächst größeren Elementes. Das Element mit dem Index 2 ist NONE.
_FIND_BEHIND := 4
Es existiert kein Element mit dem Schlüssel search. Alle Element der Map haben einen kleineren Schlüssel als search. Die Elemente mit dem Index 2 und 3 sind NONE und das Element mit dem Index 1 enthält als Zeichenkette den Schlüssel des ersten Elementes der Map.

Siehe auch:
m$find2() m$findNext() m$findPrev() m$findKeys m$keys

Weitere ähnliche Funktionen:

Maps
Funktion	Kurzinfo
catMap()	—
flatList()	Die komplette Listen- und/oder Map-Struktur in eine flache Liste überführen.
isMap()	Test, ob eine Variable mit gegebenen oder errechnetem Namen existiert und vom Typ MAP ist.
keyMap()	—
len()	Die Anzahl der Zeichen einer Zeichenkette bzw. die Anzahl der Elemente einer Liste oder einer Map bestimmen.
length()	Die Anzahl der Zeichen einer Zeichenkette bzw. die Anzahl der Elemente einer Liste oder einer Map bestimmen.
m$cat()	—
m$clear()	—
m$exist()	—
m$find2()	Ein Element in einer Map oder ersatzweise die virtuellen Nachbarn suchen.
m$find3()	Ein Element in einer Map und seine virtuellen Nachbarn suchen.
m$findKeys()	—
m$findKeysBegin()	—
m$findKeysEnd()	—
m$findKeysPCRE()	—
m$findKeysRE()	—
m$findNext()	Den Nachfolger in einer Map zu einem gegebenen Schlüssel finden.
m$findPrev()	Den Vorgänger in einer Map zu einem gegebenen Schlüssel finden.
m$keys()	—
m$length()	Die Anzahl der Elemente einer Map bestimmen.
m$map()	—
m$operation()	Operationen mit Mengen, bei denen Elemente Werte besitzen.
m$pack()	—
m$purge()	—
m$size()	—
map()	—
mapOperation()	Operationen mit Mengen, bei denen Elemente Werte besitzen.

Suchen & Ersetzen
Funktion	Kurzinfo
compilePCRE()	Eine PCRE übersetzen und einer eindeutigen ID zuweisen.
compileRE()	Eine RegEx übersetzen und einer eindeutigen ID zuweisen.
count()	—
countNum()	Die Anzahl der numerischen Elemente zählen.
countPCRE()	Die Anzahl der Treffer eines PCRE berechnen.
countRE()	Die Anzahl der Treffer eines RegEx berechnen.
countVal()	Die Anzahl der skalaren Elemente zählen.
find()	—
findAllPCRE()	Alle Vorkommen einer Zeichenkette mittels eines PCRE suchen und eine Liste mit den Fundpositionen und Fundtexten als Ergebnis liefern.
findAllRE()	Alle Vorkommen einer Zeichenkette mittels eines RegEx suchen und eine Liste mit den Fundpositionen und Fundtexten als Ergebnis liefern.
findPCRE()	Eine Zeichenkette mittels eines PCRE suchen und die Startposition dieser Zeichenkette ermitteln.
findRE()	Eine Zeichenkette mittels eines RegEx suchen und die Startposition dieser Zeichenkette ermitteln.
findReverse()	—
findTextPCRE()	Eine Zeichenkette mittels eines PCRE suchen und den gefundenen Text als Ergebnis liefern.
findTextRE()	Eine Zeichenkette mittels eines RegEx suchen und den gefundenen Text als Ergebnis liefern.
item()	—
itemPCRE()	—
itemRE()	—
m$find2()	Ein Element in einer Map oder ersatzweise die virtuellen Nachbarn suchen.
m$find3()	Ein Element in einer Map und seine virtuellen Nachbarn suchen.
m$findKeys()	—
m$findKeysBegin()	—
m$findKeysEnd()	—
m$findKeysPCRE()	—
m$findKeysRE()	—
m$findNext()	Den Nachfolger in einer Map zu einem gegebenen Schlüssel finden.
m$findPrev()	Den Vorgänger in einer Map zu einem gegebenen Schlüssel finden.
replace()	—
split()	—
splitEol()	Aus einem Text eine Liste mit den einzelnen Zeilen erzeugen.
splitPCRE()	—
splitRE()	—
splitString()	—
subst()	Eine Zeichenkette suchen und die Fundstelle durch eine andere Zeichenkette ersetzen.
substChar()	In einer Zeichenkette nach einzelnen Zeichen suchen und die Fundstellen durch Zeichenketten ersetzen.
substPCRE()	Eine Zeichenkette mittels eines Perl kompatiblen regulären Ausdrückes suchen und die Fundstelle durch eine andere Zeichenkette ersetzen.
substRE()	Eine Zeichenkette mittels eines regulären Ausdrückes suchen und die Fundstelle durch eine andere Zeichenkette ersetzen.