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.
55void operator<<(const testing::internal::Secret&, int);
56
57namespace 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)".
85class 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.
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