gtest-message.h revision 2079:65f446a2bdd7
1114407Snyan// Copyright 2005, Google Inc. 2114407Snyan// All rights reserved. 3114407Snyan// 4114407Snyan// Redistribution and use in source and binary forms, with or without 5114407Snyan// modification, are permitted provided that the following conditions are 6114407Snyan// met: 7114407Snyan// 8114407Snyan// * Redistributions of source code must retain the above copyright 9114407Snyan// notice, this list of conditions and the following disclaimer. 10114407Snyan// * Redistributions in binary form must reproduce the above 11114407Snyan// copyright notice, this list of conditions and the following disclaimer 12114407Snyan// in the documentation and/or other materials provided with the 13114407Snyan// distribution. 14114407Snyan// * Neither the name of Google Inc. nor the names of its 15114407Snyan// contributors may be used to endorse or promote products derived from 16114407Snyan// this software without specific prior written permission. 17114407Snyan// 18114407Snyan// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19114407Snyan// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20114407Snyan// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21114407Snyan// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22114407Snyan// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23114407Snyan// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24114407Snyan// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25114407Snyan// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26114407Snyan// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27119880Sobrien// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28119880Sobrien// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29119880Sobrien// 30114407Snyan// Author: wan@google.com (Zhanyong Wan) 31114407Snyan// 32114407Snyan// The Google C++ Testing Framework (Google Test) 33114407Snyan// 34114407Snyan// This header file defines the Message class. 35114407Snyan// 36114407Snyan// IMPORTANT NOTE: Due to limitation of the C++ language, we have to 37114407Snyan// leave some internal implementation details in this header file. 38114407Snyan// They are clearly marked by comments like this: 39114407Snyan// 40114407Snyan// // INTERNAL IMPLEMENTATION - DO NOT USE IN A USER PROGRAM. 41114407Snyan// 42114407Snyan// Such code is NOT meant to be used by a user directly, and is subject 43114407Snyan// to CHANGE WITHOUT NOTICE. Therefore DO NOT DEPEND ON IT in a user 44114407Snyan// program! 45114407Snyan 46114407Snyan#ifndef GTEST_INCLUDE_GTEST_GTEST_MESSAGE_H_ 47114407Snyan#define GTEST_INCLUDE_GTEST_GTEST_MESSAGE_H_ 48114407Snyan 49114407Snyan#include <limits> 50114407Snyan 51114407Snyan#include "gtest/internal/gtest-port.h" 52114407Snyan 53114407Snyan// Ensures that there is at least one operator<< in the global namespace. 54114407Snyan// See Message& operator<<(...) below for why. 55114407Snyanvoid operator<<(const testing::internal::Secret&, int); 56114407Snyan 57114407Snyannamespace testing { 58114407Snyan 59114407Snyan// The Message class works like an ostream repeater. 60114407Snyan// 61114407Snyan// Typical usage: 62114407Snyan// 63114407Snyan// 1. You stream a bunch of values to a Message object. 64274537Snyan// It will remember the text in a stringstream. 65274537Snyan// 2. Then you stream the Message object to an ostream. 66274537Snyan// This causes the text in the Message to be streamed 67274537Snyan// to the ostream. 68274537Snyan// 69274537Snyan// For example; 70114407Snyan// 71114407Snyan// testing::Message foo; 72114407Snyan// foo << 1 << " != " << 2; 73114407Snyan// std::cout << foo; 74114407Snyan// 75114407Snyan// will print "1 != 2". 76274537Snyan// 77114407Snyan// Message is not intended to be inherited from. In particular, its 78114407Snyan// destructor is not virtual. 79114407Snyan// 80114407Snyan// Note that stringstream behaves differently in gcc and in MSVC. You 81114407Snyan// can stream a NULL char pointer to it in the former, but not in the 82114407Snyan// latter (it causes an access violation if you do). The Message 83114407Snyan// class hides this difference by treating a NULL char pointer as 84114407Snyan// "(null)". 85114407Snyanclass GTEST_API_ Message { 86136890Snyan private: 87114407Snyan // The type of basic IO manipulators (endl, ends, and flush) for 88114407Snyan // narrow streams. 89114407Snyan typedef std::ostream& (*BasicNarrowIoManip)(std::ostream&); 90136890Snyan 91114407Snyan public: 92114407Snyan // Constructs an empty Message. 93114407Snyan Message(); 94114407Snyan 95114407Snyan // Copy constructor. 96114407Snyan Message(const Message& msg) : ss_(new ::std::stringstream) { // NOLINT 97114407Snyan *ss_ << msg.GetString(); 98114407Snyan } 99114407Snyan 100114407Snyan // Constructs a Message from a C-string. 101114407Snyan explicit Message(const char* str) : ss_(new ::std::stringstream) { 102114407Snyan *ss_ << str; 103114407Snyan } 104114407Snyan 105114407Snyan#if GTEST_OS_SYMBIAN 106114407Snyan // Streams a value (either a pointer or not) to this object. 107114407Snyan template <typename T> 108114407Snyan inline Message& operator <<(const T& value) { 109114407Snyan StreamHelper(typename internal::is_pointer<T>::type(), value); 110114407Snyan return *this; 111114407Snyan } 112114407Snyan#else 113114407Snyan // Streams a non-pointer value to this object. 114114407Snyan template <typename T> 115114407Snyan inline Message& operator <<(const T& val) { 116114407Snyan // Some libraries overload << for STL containers. These 117114407Snyan // overloads are defined in the global namespace instead of ::std. 118114407Snyan // 119114407Snyan // C++'s symbol lookup rule (i.e. Koenig lookup) says that these 120114407Snyan // 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. 232inline std::ostream& operator <<(std::ostream& os, const Message& sb) { 233 return os << sb.GetString(); 234} 235 236namespace 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". 242template <typename T> 243std::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_ 251