src/base/CharacterSet.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_BASE_CHARACTERSET_H
  10 #define SQUID_SRC_BASE_CHARACTERSET_H
  11
  12 #include <initializer_list>
  13 #include <iosfwd>
  14 #include <vector>
  15
  16 /// optimized set of C chars, with quick membership test and merge support
  17 class CharacterSet
  18 {
  19 public:
  20     typedef std::vector<uint8_t> Storage;
  21
  22     /// a character set with a given label and contents
  23     explicit CharacterSet(const char *label = "anonymous", const char * const chars = "");
  24
  25     /// define a character set with the given label ("anonymous" if nullptr)
  26     ///  containing characters defined in the supplied ranges
  27     /// \see addRange
  28     CharacterSet(const char *label, unsigned char low, unsigned char high);
  29
  30     /// define a character set with the given label ("anonymous" if nullptr)
  31     ///  containing characters defined in the supplied list of low-high ranges
  32     /// \see addRange
  33     CharacterSet(const char *label, std::initializer_list<std::pair<uint8_t,uint8_t>> ranges);
  34
  35     /// whether the set lacks any members
  36     bool isEmpty() const { return chars_.empty(); }
  37
  38     /// whether a given character exists in the set
  39     bool operator[](unsigned char c) const {return chars_[static_cast<uint8_t>(c)] != 0;}
  40
  41     /// add a given character to the character set
  42     CharacterSet & add(const unsigned char c);
  43
  44     /// remove a given character from the character set
  45     CharacterSet & remove(const unsigned char c);
  46
  47     /// add a list of character ranges, expressed as pairs [low,high], including both ends
  48     CharacterSet & addRange(unsigned char low, unsigned char high);
  49
  50     /// set addition: add to this set all characters that are also in rhs
  51     CharacterSet &operator +=(const CharacterSet &rhs);
  52
  53     /// set subtraction: remove all characters that are also in rhs
  54     CharacterSet &operator -=(const CharacterSet &rhs);
  55
  56     /// return a new CharacterSet containing characters not in this set
  57     ///  use the supplied label if provided, default is "complement_of_some_other_set"
  58     CharacterSet complement(const char *complementLabel = nullptr) const;
  59
  60     /// change name; handy in const declarations that use operators
  61     CharacterSet &rename(const char *label) { name = label; return *this; }
  62
  63     /// \note Ignores label
  64     bool operator == (const CharacterSet &cs) const { return chars_ == cs.chars_; }
  65     /// \note Ignores label
  66     bool operator != (const CharacterSet &cs) const { return !operator==(cs); }
  67
  68     /// prints all chars in arbitrary order, without any quoting/escaping
  69     void printChars(std::ostream &os) const;
  70
  71     /// optional set label for debugging (default: "anonymous")
  72     const char * name;
  73
  74     // common character sets, RFC 5234
  75     // A-Za-z
  76     static const CharacterSet ALPHA;
  77     // 0-1
  78     static const CharacterSet BIT;
  79     // carriage return
  80     static const CharacterSet CR;
  81     // controls
  82     static const CharacterSet CTL;
  83     // 0-9
  84     static const CharacterSet DIGIT;
  85     // double quote
  86     static const CharacterSet DQUOTE;
  87     // 0-9aAbBcCdDeEfF
  88     static const CharacterSet HEXDIG;
  89     // horizontal tab
  90     static const CharacterSet HTAB;
  91     // line feed
  92     static const CharacterSet LF;
  93     // white space
  94     static const CharacterSet SP;
  95     // visible (printable) characters
  96     static const CharacterSet VCHAR;
  97     // <space><tab>
  98     static const CharacterSet WSP;
  99
 100     // HTTP character sets, RFC 7230
 101     // ctext
 102     static const CharacterSet CTEXT;
 103     // XXX: maybe field-vchar = VCHAR / obs-text
 104     // any VCHAR except for SPECIAL
 105     static const CharacterSet TCHAR;
 106     // special VCHARs
 107     static const CharacterSet SPECIAL;
 108     // qdtext
 109     static const CharacterSet QDTEXT;
 110     // obs-text
 111     static const CharacterSet OBSTEXT;
 112
 113     // HTTP character sets, RFC 7232
 114     // etagc
 115     static const CharacterSet ETAGC;
 116
 117     // HTTP character sets, RFC 7235
 118     // token68 (internal characters only, excludes '=' terminator)
 119     static const CharacterSet TOKEN68C;
 120
 121     /// allowed URI characters that do not have a reserved purpose, RFC 3986
 122     static const CharacterSet &RFC3986_UNRESERVED();
 123
 124 private:
 125     /** index of characters in this set
 126      *
 127      * \note guaranteed to be always 256 slots big, as forced in the
 128      *  constructor. This assumption is relied upon in various methods
 129      */
 130     Storage chars_;
 131 };
 132
 133 /** CharacterSet addition
 134  *
 135  * \return a new CharacterSet containing all characters present both in lhs
 136  *  and rhs, labeled as lhs is
 137  */
 138 CharacterSet
 139 operator+ (CharacterSet lhs, const CharacterSet &rhs);
 140
 141 /** CharacterSet subtraction
 142  *
 143  * \return a new CharacterSet containing all characters present in lhs
 144  *  and not present in rhs, labeled as lhs is
 145  */
 146 CharacterSet
 147 operator- (CharacterSet lhs, const CharacterSet &rhs);
 148
 149 std::ostream&
 150 operator <<(std::ostream &, const CharacterSet &);
 151
 152 #endif /* SQUID_SRC_BASE_CHARACTERSET_H */
 153