SYNOPSIS
     string regreplace(string txt, string pattern,
                       string|closure replacepattern, int flags)

BESCHREIBUNG
     Die Funktion durchsucht den String txt nach einem Vorkommen
     des regulaeren Ausdrucks pattern, und ersetzt ihn durch
     den String replacepattern. (replacepattern kann auch eine Closure
     sein. Sie bekommt als argument den passenden Substring und muss
     den Ersatzstring zurueckliefern.)

     Im replacestring kann man via '&' auf den zum Suchausdruck
     passenden Teilstring im Original zugreifen. Mit \n (wobei n
     eine Ganzzahl ist) kann man auf den n-ten Unterausdruck
     des regulaeren Ausdrucks zugreifen. Um "&" oder "\\1" als
     Ersetzung zu erreichen, muss "\\&" bzw "\\\\1" verwendet werden.

     Beim Flag bestimmt ein gesetztes Bit 0, dass der Ausdruck so oft
     wie vorhanden ersetzt wird, sonst nur das erste Auftreten.
     Bit 1 bestimmt, ob der regulaere Ausdruck 'ed' oder 'sed' kompatibel
     ist (Bit geloescht) oder 'ex' kompatibel (gesetzt).

     Die Funktion wirkt wie s/pattern/replacepattern/flags in
     Editoren wie vi oder sed. Sie ist besonders gut geeignet um
     variable Strings zu ersetzen, im Gegensatz zu regexplode, wo
     man den String nur nach einem regulaeren Ausdruck zerlegen kann.

BEISPIELE
     // ersetzt @@wer@@ durch den Namen des Objektes
     regreplace(str,"@@wer@@",(string)obj->name(WER,2),1)

     // ersetze alle doppelten Leerzeichen durch ein einzelnes
     regreplace(str, "  *", " ", 1);

     // Sucht nach 'teilt Dir mit: ' und schliesst den nachfolgenden
     // Text mit <underline> und </underline> ein; bei jedem Auftreten.

     msgin = regreplace(msgin, "teilt Dir mit: (.*)",
                               "teilt Dir mit: <underline>\\1</underline>",
                               1);

     // Ersetzt die <underline> html-Tags durch die vt100
     // Escape-Sequenzen fuer Unterstreichung
     txt = regreplace(txt, "<underline>", "<ESC>[5m", 1);

     // Ersetzt das Wort HOUSE in Kleinbuchstaben.
     txt = regreplace(txt, "HOUSE", #'lower_case, 1);

BUGS:
     I have written that efun. It doesn't have BUGS. By definition.
     Well, in fact it crashed as I first tried it on running TAPPMud.
     *sigh*
     Marcus@TAPPMud

SIEHE AUCH
     Verwandt: regexp(E), regexplode(E), sscanf(E)
     Aehnlich: replace_personal(L)
