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//
31// The Google C++ Testing and Mocking Framework (Google Test)
32//
33// This header file defines the Message class.
34//
35// IMPORTANT NOTE: Due to limitation of the C++ language, we have to
36// leave some internal implementation details in this header file.
37// They are clearly marked by comments like this:
38//
39// // INTERNAL IMPLEMENTATION - DO NOT USE IN A USER PROGRAM.
40//
41// Such code is NOT meant to be used by a user directly, and is subject
42// to CHANGE WITHOUT NOTICE. Therefore DO NOT DEPEND ON IT in a user
43// program!
44
45// GOOGLETEST_CM0001 DO NOT DELETE
46
47#ifndef GTEST_INCLUDE_GTEST_GTEST_MESSAGE_H_
48#define GTEST_INCLUDE_GTEST_GTEST_MESSAGE_H_
49
50#include <limits>
51#include <memory>
52#include <sstream>
53
54#include "gtest/internal/gtest-port.h"
55
56GTEST_DISABLE_MSC_WARNINGS_PUSH_(4251 \
57/* class A needs to have dll-interface to be used by clients of class B */)
58
59// Ensures that there is at least one operator<< in the global namespace.
60// See Message& operator<<(...) below for why.
61void operator<<(const testing::internal::Secret&, int);
62
63namespace testing {
64
65// The Message class works like an ostream repeater.
66//
67// Typical usage:
68//
69// 1. You stream a bunch of values to a Message object.
70// It will remember the text in a stringstream.
71// 2. Then you stream the Message object to an ostream.
72// This causes the text in the Message to be streamed
73// to the ostream.
74//
75// For example;
76//
77// testing::Message foo;
78// foo << 1 << " != " << 2;
79// std::cout << foo;
80//
81// will print "1 != 2".
82//
83// Message is not intended to be inherited from. In particular, its
84// destructor is not virtual.
85//
86// Note that stringstream behaves differently in gcc and in MSVC. You
87// can stream a NULL char pointer to it in the former, but not in the
88// latter (it causes an access violation if you do). The Message
89// class hides this difference by treating a NULL char pointer as
90// "(null)".
91class GTEST_API_ Message {
92 private:
93 // The type of basic IO manipulators (endl, ends, and flush) for
94 // narrow streams.
95 typedef std::ostream& (*BasicNarrowIoManip)(std::ostream&);
96
97 public:
98 // Constructs an empty Message.
99 Message();
100
101 // Copy constructor.
102 Message(const Message& msg) : ss_(new ::std::stringstream) { // NOLINT
103 *ss_ << msg.GetString();
104 }
105
106 // Constructs a Message from a C-string.
107 explicit Message(const char* str) : ss_(new ::std::stringstream) {
108 *ss_ << str;
109 }
110
111 // Streams a non-pointer value to this object.
112 template <typename T>
113 inline Message& operator <<(const T& val) {
114 // Some libraries overload << for STL containers. These
115 // overloads are defined in the global namespace instead of ::std.
116 //
117 // C++'s symbol lookup rule (i.e. Koenig lookup) says that these
118 // overloads are visible in either the std namespace or the global
119 // namespace, but not other namespaces, including the testing
120 // namespace which Google Test's Message class is in.
121 //
122 // To allow STL containers (and other types that has a << operator
123 // defined in the global namespace) to be used in Google Test
124 // assertions, testing::Message must access the custom << operator
125 // from the global namespace. With this using declaration,
126 // overloads of << defined in the global namespace and those
127 // visible via Koenig lookup are both exposed in this function.
128 using ::operator <<;
129 *ss_ << val;
130 return *this;
131 }
132
133 // Streams a pointer value to this object.
134 //
135 // This function is an overload of the previous one. When you
136 // stream a pointer to a Message, this definition will be used as it
137 // is more specialized. (The C++ Standard, section
138 // [temp.func.order].) If you stream a non-pointer, then the
139 // previous definition will be used.
140 //
141 // The reason for this overload is that streaming a NULL pointer to
142 // ostream is undefined behavior. Depending on the compiler, you
143 // may get "0", "(nil)", "(null)", or an access violation. To
144 // ensure consistent result across compilers, we always treat NULL
145 // as "(null)".
146 template <typename T>
147 inline Message& operator <<(T* const& pointer) { // NOLINT
148 if (pointer == nullptr) {
149 *ss_ << "(null)";
150 } else {
151 *ss_ << pointer;
152 }
153 return *this;
154 }
155
156 // Since the basic IO manipulators are overloaded for both narrow
157 // and wide streams, we have to provide this specialized definition
158 // of operator <<, even though its body is the same as the
159 // templatized version above. Without this definition, streaming
160 // endl or other basic IO manipulators to Message will confuse the
161 // compiler.
162 Message& operator <<(BasicNarrowIoManip val) {
163 *ss_ << val;
164 return *this;
165 }
166
167 // Instead of 1/0, we want to see true/false for bool values.
168 Message& operator <<(bool b) {
169 return *this << (b ? "true" : "false");
170 }
171
172 // These two overloads allow streaming a wide C string to a Message
173 // using the UTF-8 encoding.
174 Message& operator <<(const wchar_t* wide_c_str);
175 Message& operator <<(wchar_t* wide_c_str);
176
177#if GTEST_HAS_STD_WSTRING
178 // Converts the given wide string to a narrow string using the UTF-8
179 // encoding, and streams the result to this Message object.
180 Message& operator <<(const ::std::wstring& wstr);
181#endif // GTEST_HAS_STD_WSTRING
182
183 // Gets the text streamed to this object so far as an std::string.
184 // Each '\0' character in the buffer is replaced with "\\0".
185 //
186 // INTERNAL IMPLEMENTATION - DO NOT USE IN A USER PROGRAM.
187 std::string GetString() const;
188
189 private:
190 // We'll hold the text streamed to this object here.
191 const std::unique_ptr< ::std::stringstream> ss_;
192
193 // We declare (but don't implement) this to prevent the compiler
194 // from implementing the assignment operator.
195 void operator=(const Message&);
196};
197
198// Streams a Message to an ostream.
199inline std::ostream& operator <<(std::ostream& os, const Message& sb) {
200 return os << sb.GetString();
201}
202
203namespace internal {
204
205// Converts a streamable value to an std::string. A NULL pointer is
206// converted to "(null)". When the input value is a ::string,
207// ::std::string, ::wstring, or ::std::wstring object, each NUL
208// character in it is replaced with "\\0".
209template <typename T>
210std::string StreamableToString(const T& streamable) {
211 return (Message() << streamable).GetString();
212}
213
214} // namespace internal
215} // namespace testing
216
217GTEST_DISABLE_MSC_WARNINGS_POP_() // 4251
218
219#endif // GTEST_INCLUDE_GTEST_GTEST_MESSAGE_H_
220