include/wvstringlist.h

   1 /* -*- Mode: C++ -*-
   2  * Worldvisions Weaver Software:
   3  *   Copyright (C) 1997-2002 Net Integration Technologies, Inc.
   4  *
   5  * WvStrings are used a lot more often than WvStringLists, so the List need
   6  * not be defined most of the time.  Include this file if you need it.
   7  *
   8  */
   9 #ifndef __WVSTRINGLIST_H
  10 #define __WVSTRINGLIST_H
  11
  12 #include "wvstring.h"
  13 #include "wvlinklist.h"
  14
  15 class WvRegex;
  16
  17 DeclareWvList2(WvStringListBase, WvString);
  18
  19 /**
  20  * This is a WvList of WvStrings, and is a really handy way to parse
  21  * strings. If you ever find yourself using strtok(3) or strpbrk(3),
  22  * or find yourself needing to parse a line of input, WvStringList,
  23  * WvStringList::split(), and WvStringList::popstr() are probably what you
  24  * want, and avoid all sorts of nasty security bugs caused by doing it any
  25  * other way.
  26  */
  27 class WvStringList : public WvStringListBase
  28 {
  29     // copy constructor: not defined anywhere!
  30     WvStringList(const WvStringList &l);
  31 public:
  32     /**
  33      * Instatiate a new WvStringList()
  34      */
  35     WvStringList() {}
  36
  37     /**
  38      * concatenates all elements of the list seperating on joinchars
  39      */
  40     WvString join(const char *joinchars = " ") const;
  41
  42     /**
  43      * split s and form a list ignoring splitchars (except at beginning and end)
  44      * ie. " happy birthday  to  you" split on " " will populate the list with
  45      * ""
  46      * "happy"
  47      * "birthday"
  48      * "to"
  49      * "you"
  50      */
  51     void split(WvStringParm s, const char *splitchars = " \t\r\n",
  52                int limit = 0);
  53     /**
  54      * split s and form a list creating null entries when there are multiple
  55      * splitchars
  56      * ie " happy birthday  to  you" split on " " will populate the list with
  57      *  ""
  58      *  "happy"
  59      *  "birthday"
  60      *  ""
  61      *  "to"
  62      *  ""
  63      *  "you"
  64      *
  65      */
  66     void splitstrict(WvStringParm s, const char *splitchars = " \t\r\n",
  67                int limit = 0);
  68
  69 #ifndef _WIN32
  70     /**
  71      * split s and form a list ignoring regex (except at beginning and end)
  72      * Note that there is no splitstrict for regexes, since the differece is
  73      * taken care of through the regex (...)+ syntax
  74      */
  75     void split(WvStringParm s, const WvRegex &regex, int limit = 0);
  76 #endif
  77
  78     /*
  79      * populate the list from an array of strings
  80      */
  81     void fill(const char * const *array);
  82
  83     void append(WvStringParm str);
  84     void append(WVSTRING_FORMAT_DECL)
  85         { append(WvString(WVSTRING_FORMAT_CALL)); }
  86     void append(WvString *strp, bool autofree, char *id = NULL);
  87
  88     /**
  89      * get the first string in the list, or an empty string if the list is empty.
  90      * Removes the returned string from the list.
  91      */
  92     WvString popstr();
  93 };
  94
  95 #endif // __WVSTRINGLIST_H