| onqtam | 8126b56 | 2016-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). |
| 9 | Most 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 | |
| 11 | ## ```operator<<``` overload for ```std::ostream``` |
| 12 | |
| 13 | This 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: |
| 14 | |
| 15 | ``` |
| 16 | std::ostream& operator<< (std::ostream& os, const T& value) { |
| 17 | os << convertMyTypeToString(value); |
| 18 | return os; |
| 19 | } |
| 20 | ``` |
| 21 | |
| 22 | (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). |
| 23 | |
| 24 | You should put this function in the same namespace as your type. |
| 25 | |
| 26 | Alternatively you may prefer to write it as a member function: |
| 27 | |
| 28 | ``` |
| 29 | std::ostream& T::operator<<(std::ostream& os) const { |
| 30 | os << convertMyTypeToString(*this); |
| 31 | return os; |
| 32 | } |
| 33 | ``` |
| 34 | |
| 35 | ## ```doctest::toString``` overload |
| 36 | |
| onqtam | b18680d | 2016-11-15 14:08:56 +0200 | [diff] [blame] | 37 | If 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```. |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 38 | |
| 39 | ``` |
| onqtam | b18680d | 2016-11-15 14:08:56 +0200 | [diff] [blame] | 40 | namespace user { |
| 41 | struct udt {}; |
| 42 | |
| 43 | doctest::String toString(const udt& value) { |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 44 | return convertMyTypeToString(value); |
| 45 | } |
| 46 | } |
| 47 | ``` |
| 48 | |
| onqtam | b18680d | 2016-11-15 14:08:56 +0200 | [diff] [blame] | 49 | Note 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. |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 50 | |
| 51 | ## ```doctest::StringMaker<T>``` specialisation |
| 52 | |
| 53 | There 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: |
| 54 | |
| 55 | ``` |
| 56 | namespace doctest { |
| 57 | template<> struct StringMaker<T> { |
| 58 | static String convert(const T& value) { |
| 59 | return convertMyTypeToString(value); |
| 60 | } |
| 61 | }; |
| 62 | } |
| 63 | ``` |
| 64 | |
| 65 | ------ |
| 66 | |
| 67 | - Check out the [**example**](../../examples/stringification/main.cpp) which shows how to stringify ```std::vector<T>``` and other types. |
| 68 | - 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 for the library because then it would have to drag the ```<string>``` header with it. |
| onqtam | 1435c01 | 2016-09-21 15:29:11 +0300 | [diff] [blame] | 69 | - 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_IOSFWD```**](configuration.html#doctest_config_use_iosfwd) 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. |
| onqtam | 8126b56 | 2016-05-27 17:01:15 +0300 | [diff] [blame] | 70 | |
| 71 | --- |
| 72 | |
| 73 | [Home](readme.html#reference) |
| 74 | |
| 75 | |
| 76 | </xmp> |
| 77 | <script src="strapdown.js/strapdown.js"></script> |
| 78 | </html> |