src/wordlist.h

   1 /*
   2  * Copyright (C) 1996-2023 The Squid Software Foundation and contributors
   3  *
   4  * Squid software is distributed under GPLv2+ license and includes
   5  * contributions from numerous individuals and organizations.
   6  * Please see the COPYING and CONTRIBUTORS files for details.
   7  */
   8
   9 #ifndef SQUID_SRC_WORDLIST_H
  10 #define SQUID_SRC_WORDLIST_H
  11
  12 #include "globals.h"
  13 #include "sbuf/List.h"
  14
  15 #include <iterator>
  16
  17 class wordlist;
  18
  19 /// minimal iterator for read-only traversal of wordlist objects
  20 class WordlistIterator
  21 {
  22 public:
  23     using value_type = const char *;
  24
  25     explicit WordlistIterator(const wordlist * const wl): w(wl) {}
  26
  27     auto operator ==(const WordlistIterator &rhs) const { return this->w == rhs.w; }
  28     auto operator !=(const WordlistIterator &rhs) const { return this->w != rhs.w; }
  29
  30     inline value_type operator *() const;
  31     inline WordlistIterator &operator++();
  32
  33 private:
  34     const wordlist *w;
  35 };
  36
  37 /** A list of C-strings
  38  *
  39  * \deprecated use SBufList instead
  40  */
  41 class wordlist
  42 {
  43     MEMPROXY_CLASS(wordlist);
  44     friend char *wordlistChopHead(wordlist **);
  45
  46 public:
  47     using const_iterator = WordlistIterator;
  48
  49     wordlist() : key(nullptr), next(nullptr) {}
  50     // create a new wordlist node, with a copy of k as key
  51     explicit wordlist(const char *k) : key(xstrdup(k)), next(nullptr) {}
  52
  53     wordlist(const wordlist &) = delete;
  54     wordlist &operator=(const wordlist &) = delete;
  55
  56     auto begin() const { return const_iterator(this); }
  57     auto end() const { return const_iterator(nullptr); }
  58
  59     char *key;
  60     wordlist *next;
  61
  62 private:
  63     // does not free data members.
  64     ~wordlist() = default;
  65 };
  66
  67 class MemBuf;
  68
  69 /** Add a null-terminated c-string to a wordlist
  70  *
  71  * \deprecated use SBufList.push_back(SBuf(word)) instead
  72  */
  73 const char *wordlistAdd(wordlist **, const char *);
  74
  75 /** Concatenate a wordlist
  76  *
  77  * \deprecated use SBufListContainerJoin(SBuf()) from sbuf/Algorithms.h instead
  78  */
  79 void wordlistCat(const wordlist *, MemBuf *);
  80
  81 /// destroy a wordlist
  82 void wordlistDestroy(wordlist **);
  83
  84 /**  Remove and destroy the first element while preserving and returning its key
  85  *
  86  * \note the returned key must be freed by the caller using safe_free
  87  * \note wl is altered so that it points to the second element
  88  * \return nullptr if pointed-to wordlist is nullptr.
  89  */
  90 char *wordlistChopHead(wordlist **);
  91
  92 inline WordlistIterator &
  93 WordlistIterator::operator++()
  94 {
  95     w = w->next;
  96     return *this;
  97 }
  98
  99 inline WordlistIterator::value_type
 100 WordlistIterator::operator*() const
 101 {
 102     return w->key;
 103 }
 104
 105 #endif /* SQUID_SRC_WORDLIST_H */
 106