Sucht und ersetzt ein Suchmuster in Form eines "regulären Ausdrucks" (regular expression) in einer Zeichenfolge.
NewStr := RegExReplace(Haystack, NeedleRegEx [, Replacement = "", OutputVarCount = "", Limit = -1, StartingPosition = 1])
| NewStr | RegExReplace() gibt in dieser Variablen eine Kopie von Haystack zurück, in der die Ersetzungen durchgeführt wurden. Wenn das Suchmuster nicht gefunden wurde, wird der Inhalt von Haystack unverändert zurückgegeben. Wenn ein Fehler auftritt (wie z.B. ein Syntaxfehler in NeedleRegEx) wird Haystack ebenfalls unverändert zurückgegeben (Ausnahme: In den Versionen vor 1.0.46.06 wurde "" zurückgegeben) und ErrorLevel wird nicht auf 0 sondern auf einen der unten angegebenen gesetzt. |
| Haystack | (Heuhaufen) Die Zeichenfolge, in der gesucht und ersetzt wird. |
| NeedleRegEx | (Nadel : Die Nadel im Heuhaufen suchen!) Das Suchmuster als "Perl-compatible Regular Expression" (PCRE). Alle Optionen müssen am Anfang des Musters eingefügt und mit einer schließenden runden Klammer ")" abgeschlossen werden. Das Muster "i)abc.*123" schaltet z.B. die Option "i" (case-insensitive) ein und sucht nach "abc", gefolgt von keinem oder beliebig vielen beliebigen Zeichen, gefolgt von "123". Wenn keine Optionen verwendet werden, ist die ")" optional: ")abc" und "abc" sind gleichbedeutend. |
| Replacement |
Die Zeichenfolge, durch die alle Treffer ersetzt werden, als normaler Text (nicht als regulärer Ausdruck). Der Text kann Rückwärtsreferenzen wie $1 enthalten, die den Treffer des ersten subpattern (Teilmusters) aus Haystack beinhaltet. Die einfachsten Rückwärtsreferenzen sind $0 bis $9, wobei $0 für den Treffer des kompletten Suchmusters steht, $1 für den Treffer des ersten Teilmusters, $2 für den des zweiten, usw. Für Rückwärtsreferenzen oberhalb von 9 (und optional auch für die bis 9), wird die Nummer in geschweifte Klammern eingeschlossen, z.B. ${10}, ${11}, usw. Bei named subpatterns (benannten Teilmustern) wird der Name anstelle der Nummer verwendet, z.B. ${SubpatternName}. Für ein normales $-Zeichen muss $$ geschrieben werden. Es ist das einzige Zeichen, das eine Sonderbehandlung benötigt, der Backslash wird nicht gebraucht, um irgend etwas zu maskieren. Um die Schreibung eines Teiltreffers zu verändern, wird dem $ ein U oder u (Großbuchstaben), ein L oder l (Kleinbuchstaben) oder ein T oderr t (Titelmodus: der erste Buchstabe jedes Wortes wird groß geschrieben, der Rest klein). $U1 und $U{1} liefern z.B. beide eine Version des Treffers des ersten Teilmusters in Großbuchstaben. Ungültige (nicht existierende) Rückwärtsreferenzen und diejenigen, die keinen Treffer in Haystack fanden -- wie eines der Teilmuster in (abc)|(xyz) -- werden als leere Zeichenfolgen behandelt. Wenn Replacement nicht angegeben wird, werden alle Treffer durch eine leere Zeichenfolge ersetzt. |
| OutputVarCount | Der nicht in Anführungszeichen eingeschlossene
Name einer Variablen, in der die Anzahl der Ersetzungen abgelegt wird
bzw. 0, wenn nichts ersetzt wurde. Weil der Inhalt von Haystack nie verändert wird, kann RegExReplace() auch dafür genutzt werden, die Anzahl des Vorkommens einer Zeichenfolge in einer anderen in OutPutVarCount zu ermitteln. |
| Limit | Wenn Limit nicht angegeben wird, gilt der Standardwert -1 und alle Vorkommen des Musters in Haystack werden ersetzt. Ansonsten kann mit Limit die maximale Zahl von Ersetzungen vorgegeben werden. Der Teil rechts von der maximalen Ersetzung in Haystack bleibt dann unverändert. |
| StartingPosition |
Wenn StartingPosition nicht angegeben wird, beginnt die Suche beim 1. Zeichen (am Anfang von Haystack). Bei Angabe von 2 beginnt sie beim zweiten, bei 3 beim dritten Zeichen, usw. Wenn StartingPosition größer ist als die Länge von Haystack, beginnt die Suche mit dem Leerstring am Ende von Haystack und findet normalerweise keinen Treffer. Wenn StartingPosition einen Wert kleiner als 1 enthält, wird dieser als Distanz zum Ende von Haystack behandelt. 0 startet die Suche z.B. beim letzten Zeichen und -1 beim vorletzten Zeichen. Wenn die Distanz größer ist als die Länge von Haystack, wird der komplette Haystack durchsucht. Unabhängig vom Wert in StartingPosition wird immer eine vollständige Kopie von Haystack zurückgegeben -- der einzige Unterschied ist, dass der Teil von Haystack links von StartingPosition immer unverändert bleibt. |
ErrorLevel wird auf einen der folgenden Werte gesetzt:
Eine Beschreibung der Optionen wie "i)abc", die die Suche unter Berücksichtigung der Groß/Kleinschreibung für das Muster "abc" abschaltet, findet sich hier.
Bei der Ersetzung eines einfachen Teilstrings ist StringReplace in der Regel schneller als RegExReplace().
Wenn die maximale Anzahl der Ersetzungen bekannt ist, kann die Angabe dieser Zahl in Limit die Performance verbessern, weil die Suche früher beendet werden kann. Außerdem kann der für die Ausführung der Anweisung benötigte Speicherplatz verringert werden. Wenn man z.B. weiß, dass es nur einen Treffer nah am Anfang einer langen Zeichenfolge geben kann, sollte man als Limit auch 1 angeben.
Für die Verbesserung der Performance werden die 100 zuletzt verwendeten regulären Ausdrücke in übersetzter Form im Hauptspeicher gehalten.
Die Option study (S) kann die Performance von regulären Ausdrücken verbessern, die z.B. in einer Schleife wiederholt aufgerufen werden.
Die meisten Zeichen wie abc123 können innerhalb eines regulären Ausdrucks normal verwendet werden. Den Zeichen \.*?+[{|()^$ sind aber bestimmte Funktionen zugeordnet. Ihnen muss deshalb ein Backslash ("\") vorangestellt werden, wenn sie als normale Zeichen behandelt werden sollen. \. ist z.B. ein normaler Punkt und \\ ein normaler Backslash. Diese Form der Maskierung ist unnötig, wenn man den Text in \Q und \E einschließt (z.B. \QNormaler Text mit Klammern ()\E).
Innerhalb eines regulären Ausdrucks können spezielle Zeichen wie Tabulator oder Zeilenvorschub sowohl mit dem AHK Escape-Zeichen (`) als auch mit dem Backslash (\) gekennzeichnet werden, `t ist z.B. gleichbedeutend mit \t.
Um die Grundbegriffe der regulären Ausdrücke zu erlernen oder das Gedächtnis aufzufrischen, siehe auch RegEx Quick Reference.
RegExMatch(), RegEx Quick Reference, StringReplace, InStr()
Übliche Quellen für Textdaten: FileRead, UrlDownloadToFile, Clipboard, GUI Edit controls
NewStr := RegExReplace("abc123123", "123$", "xyz") ; Liefert "abc123xyz", weil $ einen Treffer nur am Ende zulässt.
NewStr := RegExReplace("abc123", "i)^ABC") ; Liefert "123", weil die Suche wegen der Option i case-insensitive durchgeführt wird.
NewStr := RegExReplace("abcXYZ123", "abc(.*)123", "aaa$1zzz") ; Liefert "aaaXYZzzz" wegen der Rückwärtsreferenz $1.
NewStr := RegExReplace("abc123abc456", "abc\d+", "", ReplacementCount) ; Liefert "" und speichert 2 in ReplacementCount.
; Für weitere allgemeine RegEx Beispiele siehe auch RegEx Quick Reference.