src/utils_subst.h

   1 /**
   2  * collectd - src/utils_subst.h
   3  * Copyright (C) 2008  Sebastian Harl
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; only version 2 of the License is applicable.
   8  *
   9  * This program is distributed in the hope that it will be useful, but
  10  * WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along
  15  * with this program; if not, write to the Free Software Foundation, Inc.,
  16  * 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  17  *
  18  * Authors:
  19  *   Sebastian "tokkee" Harl <sh at tokkee.org>
  20  **/
  21
  22 /*
  23  * This module provides functions for string substitution.
  24  */
  25
  26 #ifndef UTILS_SUBST_H
  27 #define UTILS_SUBST_H 1
  28
  29 #include <stddef.h>
  30
  31 /*
  32  * subst:
  33  *
  34  * Replace a substring of a string with the specified replacement text. The
  35  * resulting string is stored in the buffer pointed to by 'buf' of length
  36  * 'buflen'. Upon success, the buffer will always be null-terminated. The
  37  * result may be truncated if the buffer is too small.
  38  *
  39  * The substring to be replaces is identified by the two offsets 'off1' and
  40  * 'off2' where 'off1' specifies the offset to the beginning of the substring
  41  * and 'off2' specifies the offset to the first byte after the substring.
  42  *
  43  * The minimum buffer size to store the complete return value (including the
  44  * terminating '\0' character) thus has to be:
  45  * off1 + strlen(replacement) + strlen(string) - off2 + 1
  46  *
  47  * Example:
  48  *
  49  *             01234567890
  50  *   string = "foo_____bar"
  51  *                ^    ^
  52  *                |    |
  53  *              off1  off2
  54  *
  55  *   off1 = 3
  56  *   off2 = 8
  57  *
  58  *   replacement = " - "
  59  *
  60  *   -> "foo - bar"
  61  *
  62  * The function returns 'buf' on success, NULL else.
  63  */
  64 char *subst (char *buf, size_t buflen, const char *string, int off1, int off2,
  65                 const char *replacement);
  66
  67 /*
  68  * asubst:
  69  *
  70  * This function is very similar to subst(). It differs in that it
  71  * automatically allocates the memory required for the return value which the
  72  * user then has to free himself.
  73  *
  74  * Returns the newly allocated result string on success, NULL else.
  75  */
  76 char *asubst (const char *string, int off1, int off2, const char *replacement);
  77
  78 /*
  79  * subst_string:
  80  *
  81  * Works like `subst', but instead of specifying start and end offsets you
  82  * specify `needle', the string that is to be replaced. If `needle' is found
  83  * in `string' (using strstr(3)), the offset is calculated and `subst' is
  84  * called with the determined parameters.
  85  *
  86  * If the substring is not found, no error will be indicated and
  87  * `subst_string' works mostly like `strncpy'.
  88  *
  89  * If the substring appears multiple times, all appearances will be replaced.
  90  * If the substring has been found `buflen' times, an endless loop is assumed
  91  * and the loop is broken. A warning is printed and the function returns
  92  * success.
  93  */
  94 char *subst_string (char *buf, size_t buflen, const char *string,
  95                 const char *needle, const char *replacement);
  96
  97 #endif /* UTILS_SUBST_H */
  98
  99 /* vim: set sw=4 ts=4 tw=78 noexpandtab : */
 100