UnitTests/cppunit/include/cppunit/Message.h

   1 #ifndef CPPUNIT_MESSAGE_H
   2 #define CPPUNIT_MESSAGE_H
   3
   4 #include <cppunit/Portability.h>
   5
   6 #if CPPUNIT_NEED_DLL_DECL
   7 #pragma warning( push )
   8 #pragma warning( disable: 4251 )  // X needs to have dll-interface to be used by clients of class Z
   9 #endif
  10
  11 #include <cppunit/portability/CppUnitDeque.h>
  12 #include <string>
  13
  14
  15 CPPUNIT_NS_BEGIN
  16
  17
  18 #if CPPUNIT_NEED_DLL_DECL
  19 //  template class CPPUNIT_API std::deque<std::string>;
  20 #endif
  21
  22 /*! \brief Message associated to an Exception.
  23  * \ingroup CreatingNewAssertions
  24  *  A message is composed of two items:
  25  *  - a short description (~20/30 characters)
  26  *  - a list of detail strings
  27  *
  28  *  The short description is used to indicate how the detail strings should be
  29  *  interpreted. It usually indicates the failure types, such as
  30  *  "assertion failed", "forced failure", "unexpected exception caught",
  31  *  "equality assertion failed"... It should not contains new line character (\n).
  32  *
  33  *  Detail strings are used to provide more information about the failure. It
  34  *  can contains the asserted expression, the expected and actual values in an
  35  *  equality assertion, some addional messages... Detail strings can contains
  36  *  new line characters (\n).
  37  */
  38 class CPPUNIT_API Message
  39 {
  40 public:
  41   Message();
  42
  43   // Ensure thread-safe copy by detaching the string.
  44   Message( const Message &other );
  45
  46   explicit Message( const std::string &shortDescription );
  47
  48   Message( const std::string &shortDescription,
  49            const std::string &detail1 );
  50
  51   Message( const std::string &shortDescription,
  52            const std::string &detail1,
  53            const std::string &detail2 );
  54
  55   Message( const std::string &shortDescription,
  56            const std::string &detail1,
  57            const std::string &detail2,
  58            const std::string &detail3 );
  59
  60   Message &operator =( const Message &other );
  61
  62   /*! \brief Returns the short description.
  63    * \return Short description.
  64    */
  65   const std::string &shortDescription() const;
  66
  67   /*! \brief Returns the number of detail string.
  68    * \return Number of detail string.
  69    */
  70   int detailCount() const;
  71
  72   /*! \brief Returns the detail at the specified index.
  73    * \param index Zero based index of the detail string to return.
  74    * \returns Detail string at the specified index.
  75    * \exception std::invalid_argument if \a index < 0 or index >= detailCount().
  76    */
  77   std::string detailAt( int index ) const;
  78
  79   /*! \brief Returns a string that represents a list of the detail strings.
  80    *
  81    * Example:
  82    * \code
  83    * Message message( "not equal", "Expected: 3", "Actual: 7" );
  84    * std::string details = message.details();
  85    * // details contains:
  86    * // "- Expected: 3\n- Actual: 7\n"  \endcode
  87    *
  88    * \return A string that is a concatenation of all the detail strings. Each detail
  89    *         string is prefixed with '- ' and suffixed with '\n' before being
  90    *         concatenated to the other.
  91    */
  92   std::string details() const;
  93
  94   /*! \brief Removes all detail strings.
  95    */
  96   void clearDetails();
  97
  98   /*! \brief Adds a single detail string.
  99    * \param detail Detail string to add.
 100    */
 101   void addDetail( const std::string &detail );
 102
 103   /*! \brief Adds two detail strings.
 104    * \param detail1 Detail string to add.
 105    * \param detail2 Detail string to add.
 106    */
 107   void addDetail( const std::string &detail1,
 108                   const std::string &detail2 );
 109
 110   /*! \brief Adds three detail strings.
 111    * \param detail1 Detail string to add.
 112    * \param detail2 Detail string to add.
 113    * \param detail3 Detail string to add.
 114    */
 115   void addDetail( const std::string &detail1,
 116                   const std::string &detail2,
 117                   const std::string &detail3 );
 118
 119   /*! \brief Adds the detail strings of the specified message.
 120    * \param message All the detail strings of this message are added to this one.
 121    */
 122   void addDetail( const Message &message );
 123
 124   /*! \brief Sets the short description.
 125    * \param shortDescription New short description.
 126    */
 127   void setShortDescription( const std::string &shortDescription );
 128
 129   /*! \brief Tests if a message is identical to another one.
 130    * \param other Message this message is compared to.
 131    * \return \c true if the two message are identical, \c false otherwise.
 132    */
 133   bool operator ==( const Message &other ) const;
 134
 135   /*! \brief Tests if a message is different from another one.
 136    * \param other Message this message is compared to.
 137    * \return \c true if the two message are not identical, \c false otherwise.
 138    */
 139   bool operator !=( const Message &other ) const;
 140
 141 private:
 142   std::string m_shortDescription;
 143
 144   typedef CppUnitDeque<std::string> Details;
 145   Details m_details;
 146 };
 147
 148
 149 CPPUNIT_NS_END
 150
 151 #if CPPUNIT_NEED_DLL_DECL
 152 #pragma warning( pop )
 153 #endif
 154
 155
 156 #endif  // CPPUNIT_MESSAGE_H