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