src/base/Raw.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 /* DEBUG: section 00    Debug Routines */
  10
  11 #ifndef SQUID_SRC_BASE_RAW_H
  12 #define SQUID_SRC_BASE_RAW_H
  13
  14 #include <iosfwd>
  15
  16 /// Prints raw and/or non-terminated data safely, efficiently, and beautifully.
  17 /// Allows raw data debugging in debugs() statements with low debugging levels
  18 /// by printing only if higher section debugging levels are configured:
  19 ///   debugs(11, DBG_IMPORTANT, "always printed" << Raw(may be printed...));
  20 class Raw
  21 {
  22 public:
  23     Raw(const char *label, const char *data, const size_t size):
  24         level(-1), label_(label), data_(data), size_(size), useHex_(false), useGap_(true) {}
  25
  26     /// limit data printing to at least the given debugging level
  27     Raw &minLevel(const int aLevel) { level = aLevel; return *this; }
  28
  29     /// print data using two hex digits per byte (decoder: xxd -r -p)
  30     Raw &hex() { useHex_ = true; return *this; }
  31
  32     Raw &gap(bool useGap = true) { useGap_ = useGap; return *this; }
  33
  34     /// If debugging is prohibited by the current debugs() or section level,
  35     /// prints nothing. Otherwise, dumps data using one of these formats:
  36     ///   " label[size]=data" if label was set and data size is positive
  37     ///   " label[0]" if label was set and data size is zero
  38     ///   " data" if label was not set and data size is positive
  39     ///   "" (i.e., prints nothing) if label was not set and data size is zero
  40     std::ostream &print(std::ostream &os) const;
  41
  42     /// Minimum section debugging level necessary for printing. By default,
  43     /// small strings are always printed while large strings are only printed
  44     /// if DBG_DATA debugging level is enabled.
  45     int level;
  46
  47 private:
  48     void printHex(std::ostream &os) const;
  49
  50     const char *label_; ///< optional data name or ID; triggers size printing
  51     const char *data_; ///< raw data to be printed
  52     size_t size_; ///< data length
  53     bool useHex_; ///< whether hex() has been called
  54     bool useGap_; ///< whether to print leading space if label is missing
  55 };
  56
  57 inline std::ostream &
  58 operator <<(std::ostream &os, const Raw &raw)
  59 {
  60     raw.print(os);
  61     return os;
  62 }
  63
  64 #endif /* SQUID_SRC_BASE_RAW_H */
  65