ut/gtest/googletest/include/gtest/gtest-message.h

   1 // Copyright 2005, Google Inc.
   2 // All rights reserved.
   3 //
   4 // Redistribution and use in source and binary forms, with or without
   5 // modification, are permitted provided that the following conditions are
   6 // met:
   7 //
   8 //     * Redistributions of source code must retain the above copyright
   9 // notice, this list of conditions and the following disclaimer.
  10 //     * Redistributions in binary form must reproduce the above
  11 // copyright notice, this list of conditions and the following disclaimer
  12 // in the documentation and/or other materials provided with the
  13 // distribution.
  14 //     * Neither the name of Google Inc. nor the names of its
  15 // contributors may be used to endorse or promote products derived from
  16 // this software without specific prior written permission.
  17 //
  18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29 //
  30 // Author: wan@google.com (Zhanyong Wan)
  31 //
  32 // The Google C++ Testing Framework (Google Test)
  33 //
  34 // This header file defines the Message class.
  35 //
  36 // IMPORTANT NOTE: Due to limitation of the C++ language, we have to
  37 // leave some internal implementation details in this header file.
  38 // They are clearly marked by comments like this:
  39 //
  40 //   // INTERNAL IMPLEMENTATION - DO NOT USE IN A USER PROGRAM.
  41 //
  42 // Such code is NOT meant to be used by a user directly, and is subject
  43 // to CHANGE WITHOUT NOTICE.  Therefore DO NOT DEPEND ON IT in a user
  44 // program!
  45
  46 #ifndef GTEST_INCLUDE_GTEST_GTEST_MESSAGE_H_
  47 #define GTEST_INCLUDE_GTEST_GTEST_MESSAGE_H_
  48
  49 #include <limits>
  50
  51 #include "gtest/internal/gtest-port.h"
  52
  53 // Ensures that there is at least one operator<< in the global namespace.
  54 // See Message& operator<<(...) below for why.
  55 void operator<<(const testing::internal::Secret&, int);
  56
  57 namespace testing {
  58
  59 // The Message class works like an ostream repeater.
  60 //
  61 // Typical usage:
  62 //
  63 //   1. You stream a bunch of values to a Message object.
  64 //      It will remember the text in a stringstream.
  65 //   2. Then you stream the Message object to an ostream.
  66 //      This causes the text in the Message to be streamed
  67 //      to the ostream.
  68 //
  69 // For example;
  70 //
  71 //   testing::Message foo;
  72 //   foo << 1 << " != " << 2;
  73 //   std::cout << foo;
  74 //
  75 // will print "1 != 2".
  76 //
  77 // Message is not intended to be inherited from.  In particular, its
  78 // destructor is not virtual.
  79 //
  80 // Note that stringstream behaves differently in gcc and in MSVC.  You
  81 // can stream a NULL char pointer to it in the former, but not in the
  82 // latter (it causes an access violation if you do).  The Message
  83 // class hides this difference by treating a NULL char pointer as
  84 // "(null)".
  85 class GTEST_API_ Message {
  86  private:
  87   // The type of basic IO manipulators (endl, ends, and flush) for
  88   // narrow streams.
  89   typedef std::ostream& (*BasicNarrowIoManip)(std::ostream&);
  90
  91  public:
  92   // Constructs an empty Message.
  93   Message();
  94
  95   // Copy constructor.
  96   Message(const Message& msg) : ss_(new ::std::stringstream) {  // NOLINT
  97     *ss_ << msg.GetString();
  98   }
  99
 100   // Constructs a Message from a C-string.
 101   explicit Message(const char* str) : ss_(new ::std::stringstream) {
 102     *ss_ << str;
 103   }
 104
 105 #if GTEST_OS_SYMBIAN
 106   // Streams a value (either a pointer or not) to this object.
 107   template <typename T>
 108   inline Message& operator <<(const T& value) {
 109     StreamHelper(typename internal::is_pointer<T>::type(), value);
 110     return *this;
 111   }
 112 #else
 113   // Streams a non-pointer value to this object.
 114   template <typename T>
 115   inline Message& operator <<(const T& val) {
 116     // Some libraries overload << for STL containers.  These
 117     // overloads are defined in the global namespace instead of ::std.
 118     //
 119     // C++'s symbol lookup rule (i.e. Koenig lookup) says that these
 120     // overloads are visible in either the std namespace or the global
 121     // namespace, but not other namespaces, including the testing
 122     // namespace which Google Test's Message class is in.
 123     //
 124     // To allow STL containers (and other types that has a << operator
 125     // defined in the global namespace) to be used in Google Test
 126     // assertions, testing::Message must access the custom << operator
 127     // from the global namespace.  With this using declaration,
 128     // overloads of << defined in the global namespace and those
 129     // visible via Koenig lookup are both exposed in this function.
 130     using ::operator <<;
 131     *ss_ << val;
 132     return *this;
 133   }
 134
 135   // Streams a pointer value to this object.
 136   //
 137   // This function is an overload of the previous one.  When you
 138   // stream a pointer to a Message, this definition will be used as it
 139   // is more specialized.  (The C++ Standard, section
 140   // [temp.func.order].)  If you stream a non-pointer, then the
 141   // previous definition will be used.
 142   //
 143   // The reason for this overload is that streaming a NULL pointer to
 144   // ostream is undefined behavior.  Depending on the compiler, you
 145   // may get "0", "(nil)", "(null)", or an access violation.  To
 146   // ensure consistent result across compilers, we always treat NULL
 147   // as "(null)".
 148   template <typename T>
 149   inline Message& operator <<(T* const& pointer) {  // NOLINT
 150     if (pointer == NULL) {
 151       *ss_ << "(null)";
 152     } else {
 153       *ss_ << pointer;
 154     }
 155     return *this;
 156   }
 157 #endif  // GTEST_OS_SYMBIAN
 158
 159   // Since the basic IO manipulators are overloaded for both narrow
 160   // and wide streams, we have to provide this specialized definition
 161   // of operator <<, even though its body is the same as the
 162   // templatized version above.  Without this definition, streaming
 163   // endl or other basic IO manipulators to Message will confuse the
 164   // compiler.
 165   Message& operator <<(BasicNarrowIoManip val) {
 166     *ss_ << val;
 167     return *this;
 168   }
 169
 170   // Instead of 1/0, we want to see true/false for bool values.
 171   Message& operator <<(bool b) {
 172     return *this << (b ? "true" : "false");
 173   }
 174
 175   // These two overloads allow streaming a wide C string to a Message
 176   // using the UTF-8 encoding.
 177   Message& operator <<(const wchar_t* wide_c_str);
 178   Message& operator <<(wchar_t* wide_c_str);
 179
 180 #if GTEST_HAS_STD_WSTRING
 181   // Converts the given wide string to a narrow string using the UTF-8
 182   // encoding, and streams the result to this Message object.
 183   Message& operator <<(const ::std::wstring& wstr);
 184 #endif  // GTEST_HAS_STD_WSTRING
 185
 186 #if GTEST_HAS_GLOBAL_WSTRING
 187   // Converts the given wide string to a narrow string using the UTF-8
 188   // encoding, and streams the result to this Message object.
 189   Message& operator <<(const ::wstring& wstr);
 190 #endif  // GTEST_HAS_GLOBAL_WSTRING
 191
 192   // Gets the text streamed to this object so far as an std::string.
 193   // Each '\0' character in the buffer is replaced with "\\0".
 194   //
 195   // INTERNAL IMPLEMENTATION - DO NOT USE IN A USER PROGRAM.
 196   std::string GetString() const;
 197
 198  private:
 199
 200 #if GTEST_OS_SYMBIAN
 201   // These are needed as the Nokia Symbian Compiler cannot decide between
 202   // const T& and const T* in a function template. The Nokia compiler _can_
 203   // decide between class template specializations for T and T*, so a
 204   // tr1::type_traits-like is_pointer works, and we can overload on that.
 205   template <typename T>
 206   inline void StreamHelper(internal::true_type /*is_pointer*/, T* pointer) {
 207     if (pointer == NULL) {
 208       *ss_ << "(null)";
 209     } else {
 210       *ss_ << pointer;
 211     }
 212   }
 213   template <typename T>
 214   inline void StreamHelper(internal::false_type /*is_pointer*/,
 215                            const T& value) {
 216     // See the comments in Message& operator <<(const T&) above for why
 217     // we need this using statement.
 218     using ::operator <<;
 219     *ss_ << value;
 220   }
 221 #endif  // GTEST_OS_SYMBIAN
 222
 223   // We'll hold the text streamed to this object here.
 224   const internal::scoped_ptr< ::std::stringstream> ss_;
 225
 226   // We declare (but don't implement) this to prevent the compiler
 227   // from implementing the assignment operator.
 228   void operator=(const Message&);
 229 };
 230
 231 // Streams a Message to an ostream.
 232 inline std::ostream& operator <<(std::ostream& os, const Message& sb) {
 233   return os << sb.GetString();
 234 }
 235
 236 namespace internal {
 237
 238 // Converts a streamable value to an std::string.  A NULL pointer is
 239 // converted to "(null)".  When the input value is a ::string,
 240 // ::std::string, ::wstring, or ::std::wstring object, each NUL
 241 // character in it is replaced with "\\0".
 242 template <typename T>
 243 std::string StreamableToString(const T& streamable) {
 244   return (Message() << streamable).GetString();
 245 }
 246
 247 }  // namespace internal
 248 }  // namespace testing
 249
 250 #endif  // GTEST_INCLUDE_GTEST_GTEST_MESSAGE_H_