1 files changed, 73 insertions, 0 deletions
diff --git a/Utilities/PCRE/pcre_subst/pcre_subst.3 b/Utilities/PCRE/pcre_subst/pcre_subst.3
new file mode 100644
index 0000000..b3c269b
--- /dev/null
+++ b/Utilities/PCRE/pcre_subst/pcre_subst.3
@@ -0,0 +1,73 @@
+.TH PCRE 3
+.SH NAME
+pcre_subst - Perl-compatible regular expression subsitution.
+.SH SYNOPSIS
+.B #include <pcre.h>
+.br
+.B #include <pcre_subst.h>
+.PP
+.SM
+.br
+int pcre_exec(const pcre *\fIcode\fR, const pcre_extra *\fIextra\fR,
+.ti +5n
+const char *\fIsubject\fR, int \fIlength\fR, int \fIstartoffset\fR,
+.ti +5n
+int \fIoptions\fR, char *\fIreplacement\fR);
+
+
+
+.SH DESCRIPTION
+\fBpcre_subst\fR is a convenience routine that calls \fIpcre_exec\fR,
+and returns a freshly allocated string based on the \fIsubject\fR with
+the \fIreplacement\fR action applied. Unlike \fIsubject\fR, whics is
+passed as a byte array with a length, \fIreplacement\fR is expected to
+be a zero terminated string (most users will just pass \fIstrlen(subject)\fR
+as the \fIlength\fR).
+
+.br
+If no match is found, pcre_subst returns NULL. The returned string is zero
+terminated (note that \fIsubject\fR doesn't have to be). For information
+on the \fIcode\fR, \fIextra\fR, \fIsubject\fR, \fIlength\fR,
+\fIstartoffset\fR and \fIoptions\fR parameters, please see \fBpcre(3)\fR.
+
+.SH REPLACEMENT STRING
+The replacement string supports a subset of the PERL replacement string.
+In particular, \\1 style escapes are not supported (actually, only the
+$1 style is handled).
+
+.SH EXAMPLE
+.Bd -literal -compact
+#include <stdio.h>
+#include <pcre.h>
+#include "pcre_subst.h"
+
+int
+main()
+{
+    char *pat = "quick\\\\s(\\\\w+)\\\\s(fox)";
+    char *rep = "$1ish $2";
+    char *str = "The quick brown foxy";
+    char *newstr;
+    const char *err;
+    int erroff;
+    pcre_extra *extra;
+    pcre *p = pcre_compile(pat, 0, &err, &erroff, NULL);
+    if (p == NULL) {
+        fprintf(stderr, "%s at %d\\n", err, erroff);
+        exit(1);
+    }
+    extra = pcre_study(p, 0, &err);
+    if (err != NULL)
+        fprintf(stderr, "Study %s: %s\\n", pat, err);
+    newstr = pcre_subst(ppat, extra, str, strlen(str),
+                        0, 0, rep);
+    if (newstr) {
+        printf("New string: %s\\n", newstr);
+        pcre_free(newstr);
+    };
+    return 0;
+}
+.Ed
+
+.SH SEE ALSO
+pcre(3)