From 8fc3402eeef449d1a0b7dfa10a2f316a181d8a27 Mon Sep 17 00:00:00 2001
From: Pekka Riikonen <priikone@silcnet.org>
Date: Sun, 13 Jan 2008 15:20:37 +0000
Subject: [PATCH] 	Comment changes.

---
 lib/silcutil/silcregex.h | 64 ++++++++++++++++++++++++++++++++++++++--
 lib/silcutil/silcstack.h |  2 +-
 2 files changed, 63 insertions(+), 3 deletions(-)

diff --git a/lib/silcutil/silcregex.h b/lib/silcutil/silcregex.h
index ed23fbc5..8b5a6654 100644
--- a/lib/silcutil/silcregex.h
+++ b/lib/silcutil/silcregex.h
@@ -27,7 +27,8 @@
  * The interface also provides many convenience functions to make the use
  * of regular expressions easier.  Especially the silc_regex allows very
  * simple way to match strings against regular expressions and get the
- * exact match or matches as a return.
+ * exact match or matches as a return.  The silc_subst provides simple and
+ * familiar way to match and substitute strings (Sed syntax).
  *
  * The regex syntax follows POSIX regex syntax:
  *
@@ -275,7 +276,11 @@ void silc_regex_free(SilcRegex regexp);
  *    The first (whole) match is returned to `match' buffer if it is non-NULL.
  *    The variable argument list are buffers where multiple matches are
  *    returned in case of group (parenthesized) regular expression.  The caller
- *    needs to know how many pointers to provide, in order to get all matches.
+ *    needs to know how many pointers to provide in order to get all matches.
+ *    If a particular group is optional, a buffer pointer still must be given
+ *    as argument for it, however, if it did not match the returned buffer
+ *    length is 0 and data pointer is NULL.
+ *
  *    If `match' is non-NULL the variable argument list must be ended with
  *    NULL.  The data in the `match' and in any other buffer is from `string'
  *    and must not be freed by the caller.
@@ -318,6 +323,61 @@ SilcBool silc_regex(const char *string, const char *regex,
 SilcBool silc_regex_buffer(SilcBuffer buffer, const char *regex,
 			   SilcBuffer match, ...);
 
+/****f* silcutil/SilcRegexAPI/silc_subst
+ *
+ * SYNOPSIS
+ *
+ *    SilcBool silc_subst(SilcBuffer buffer, const char *subst);
+ *
+ * DESCRIPTION
+ *
+ *    Regular expression matching and substitution in `buffer' according
+ *    to the substitution expression `subst'.  This function provides
+ *    Sed (Stream Editor) style substitution interface.  The `subst' may
+ *    be of following formats:
+ *
+ *    's/REGEXP/REPLACEMENT/FLAGS'
+ *
+ *    Matches regular expression REGEXP in each line in the buffer and
+ *    substitutes the match with REPLACEMENT.
+ *
+ *    'ADDRs/REGEXP/REPLACEMENT/FLAGS'
+ *
+ *    Selects lines in the buffer matching the address ADDR and matches the
+ *    regular expression REGEXP in the line and substitutes the match with
+ *    REPLACEMENT.
+ *
+ *    The ADDR may be of following format:
+ *
+ *    /REGEXP/       Matches only lines matching the regular expression
+ *    NUMBER         Matches only the specified line number (1-n)
+ *    $              Matches only the last line
+ *
+ *    The FLAGS may be of following format:
+ *
+ *    no FLAGS       Finds first match in the line and replaces that
+ *    g              Finds and replaces all matches in the line
+ *
+ *    An '!' may precede the 's'.  In that case the ADDR is not matched.
+ *
+ *    Returns TRUE if the match and replacement was done, FALSE in case
+ *    of error, and sets the silc_errno.
+ *
+ *    If you need to match and/or replace '/' characters, they must be
+ *    escaped with '\' (C-style escaping for '\' is '\\').
+ *
+ *    If you need more versatile ways to modify the buffer you may consider
+ *    using the SILC_STR_REGEX in SILC Buffer Format API directly.  This
+ *    function only provides basic matching and substitution.
+ *
+ * EXAMPLE
+ *
+ *    // Replace all foos with bar on all lines in the buffer
+ *    silc_subst(buffer, "s/foo/bar/g");
+ *
+ ***/
+SilcBool silc_subst(SilcBuffer buffer, const char *subst);
+
 /* Backwards support */
 #define silc_string_regex_match(regex, string) silc_regex(string, regex, NULL)
 
diff --git a/lib/silcutil/silcstack.h b/lib/silcutil/silcstack.h
index 017a55d0..f2663eef 100644
--- a/lib/silcutil/silcstack.h
+++ b/lib/silcutil/silcstack.h
@@ -21,7 +21,7 @@
  *
  * DESCRIPTION
  *
- * Implementation of data stack which can be used to allocate memory from
+ * Implementation of data stack which can be used to do fast allocations from
  * the stack.  Basically SilcStack is a pre-allocated memory pool system
  * which allows fast memory allocation for routines and applications that
  * frequently allocate small amounts of memory.  Other advantage of this
-- 
2.24.0