Gitiles
Code Review Sign In
gerrit.cesnet.cz / github / onqtam / doctest / 505b05ccc61d731ac82085fce0e3c59633a2bee5 / . / doc / html_generated / stringification.html
blob: 894b5c8f066ab4f4e28826f3ab6977db3b757946 [file] [log] [blame]
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]1<!DOCTYPE html>
2<html>
3<title>stringification</title>
4<xmp theme="united" style="display:none;">
5
6## String conversions
7
8**doctest** needs to be able to convert types you use in assertions and logging expressions into strings (for logging and reporting purposes).
9Most built-in types are supported out of the box but there are three ways that you can tell **doctest** how to convert your own types (or other, third-party types) into strings.
10
onqtam68681e62018-05-10 16:18:17 +0300[diff] [blame]11For stringifying enums checkout [this issue](https://github.com/onqtam/doctest/issues/121).
12
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]13## ```operator<<``` overload for ```std::ostream```
14
15This is the standard way of providing string conversions in C++ - and the chances are you may already provide this for your own purposes. If you're not familiar with this idiom it involves writing a free function of the form:
16
17```
18std::ostream& operator<< (std::ostream& os, const T& value) {
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]19 os << convertMyTypeToString(value);
20 return os;
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]21}
22```
23
24(where ```T``` is your type and ```convertMyTypeToString``` is where you'll write whatever code is necessary to make your type printable - it doesn't have to be in another function).
25
26You should put this function in the same namespace as your type.
27
28Alternatively you may prefer to write it as a member function:
29
30```
31std::ostream& T::operator<<(std::ostream& os) const {
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]32 os << convertMyTypeToString(*this);
33 return os;
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]34}
35```
36
37## ```doctest::toString``` overload
38
onqtamb18680d2016-11-15 14:08:56 +0200[diff] [blame]39If you don't want to provide an ```operator<<``` overload, or you want to convert your type differently for testing purposes, you can provide an overload for ```toString()``` for your type which returns ```doctest::String```.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]40
41```
onqtamb18680d2016-11-15 14:08:56 +0200[diff] [blame]42namespace user {
43 struct udt {};
44
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]45 doctest::String toString(const udt& value) {
46 return convertMyTypeToString(value);
47 }
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]48}
49```
50
onqtamb18680d2016-11-15 14:08:56 +0200[diff] [blame]51Note that the function must be in the same namespace as your type. If the type is not in any namespace - then the overload should be in the global namespace as well. ```convertMyTypeToString``` is where you'll write whatever code is necessary to make your type printable.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]52
53## ```doctest::StringMaker<T>``` specialisation
54
55There are some cases where overloading ```toString``` does not work as expected. Specialising ```StringMaker<T>``` gives you more precise and reliable control - but at the cost of slightly more code and complexity:
56
57```
58namespace doctest {
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]59 template<> struct StringMaker<T> {
60 static String convert(const T& value) {
61 return convertMyTypeToString(value);
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]62 }
63 };
64}
65```
66
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]67## Translating exceptions
68
onqtam2d97b852018-11-30 18:06:17 +0200[diff] [blame]69By default all exceptions deriving from ```std::exception``` will be translated to strings by calling the ```what()``` method (also C strings). For exception types that do not derive from ```std::exception``` - or if ```what()``` does not return a suitable string - use ```REGISTER_EXCEPTION_TRANSLATOR```. This defines a function that takes your exception type and returns a ```doctest::String```. It can appear anywhere in the code - it doesn't have to be in the same translation unit. For example:
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]70
71```
72REGISTER_EXCEPTION_TRANSLATOR(MyType& ex) {
73 return doctest::String(ex.message());
74}
75```
76
77Note that the exception may be accepted without a reference but it is considered bad practice in C++.
78
79An alternative way to register an exception translator is to do the following in some function - before executing any tests:
80
81```
82 // adding a lambda - the signature required is `doctest::String(exception_type)`
83 doctest::registerExceptionTranslator<int>([](int in){ return doctest::toString(in); });
84```
85
86The order of registering exception translators can be controlled - simply call the explicit function in the required order or list the exception translators with the macro in a top-to-bottom fashion in a single translation unit - everything that auto-registers in doctest works in a top-to-bottom way for a single translation unit (source file).
87
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]88You could also [override the translation mechanism](https://github.com/catchorg/Catch2/issues/539#issuecomment-454549904) for exceptions deriving from ```std::exception```.
89
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]90------
91
onqtamb8220c52017-05-16 00:21:15 +0300[diff] [blame]92- Check out the [**example**](../../examples/all_features/stringification.cpp) which shows how to stringify ```std::vector<T>``` and other types/exceptions.
93- Note that the type ```String``` is used when specializing ```StringMaker<T>``` or overloading ```toString()``` - it is the string type **doctest** works with. ```std::string``` is not an option because doctest would have to include the ```<string>``` header.
onqtam92dce5b2019-03-23 14:24:47 +0200[diff] [blame]94- To support the ```operator<<(std::ostream&...``` stringification the library has to offer a forward declaration of ```std::ostream``` and that is what the library does - but it is forbidden by the standard. It currently works everywhere - on all tested compilers - but if the user wishes to be 100% standards compliant - then the [**```DOCTEST_CONFIG_USE_STD_HEADERS```**](configuration.html#doctest_config_use_std_headers) identifier can be used to force the inclusion of ```<iosfwd>```. The reason the header is not included by default is that on MSVC (for example) it drags a whole bunch of stuff with it - and after the preprocessor is finished the translation unit has grown to 42k lines of C++ code - while Clang and the libc++ are so well implemented that including ```<iosfwd>``` there results in 400 lines of code.
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]95
96---
97
98[Home](readme.html#reference)
99
onqtamf8d57192018-08-23 16:02:12 +0300[diff] [blame]100<p align="center"><img src="../../scripts/data/logo/icon_2.svg"></p>
101
onqtam8126b562016-05-27 17:01:15 +0300[diff] [blame]102
103</xmp>
104<script src="strapdown.js/strapdown.js"></script>
105</html>