catch2/docs/tostring.md

133 lines
4.7 KiB
Markdown
Raw Permalink Normal View History

2017-08-24 15:21:36 +02:00
<a id="top"></a>
2014-12-09 19:54:35 +01:00
# String conversions
2018-09-05 10:01:54 +02:00
**Contents**<br>
[operator << overload for std::ostream](#operator--overload-for-stdostream)<br>
[Catch::StringMaker specialisation](#catchstringmaker-specialisation)<br>
[Catch::is_range specialisation](#catchis_range-specialisation)<br>
2018-09-05 10:01:54 +02:00
[Exceptions](#exceptions)<br>
2019-04-21 19:32:20 +02:00
[Enums](#enums)<br>
[Floating point precision](#floating-point-precision)<br>
2018-09-05 10:01:54 +02:00
2014-12-09 19:54:35 +01:00
Catch needs to be able to convert types you use in assertions and logging expressions into strings (for logging and reporting purposes).
Most built-in or std types are supported out of the box but there are two ways that you can tell Catch how to convert your own types (or other, third-party types) into strings.
2014-12-09 19:54:35 +01:00
## operator << overload for std::ostream
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:
```cpp
2014-12-12 09:29:21 +01:00
std::ostream& operator << ( std::ostream& os, T const& value ) {
os << convertMyTypeToString( value );
return os;
2014-12-12 09:29:21 +01:00
}
```
2014-12-09 19:54:35 +01:00
(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).
You should put this function in the same namespace as your type, or the global namespace, and have it declared before including Catch's header.
2014-12-09 19:54:35 +01:00
## Catch::StringMaker specialisation
If you don't want to provide an ```operator <<``` overload, or you want to convert your type differently for testing purposes, you can provide a specialization for `Catch::StringMaker<T>`:
2015-05-20 19:12:40 +02:00
2019-04-27 19:50:05 +02:00
```cpp
2015-05-20 19:12:40 +02:00
namespace Catch {
template<>
struct StringMaker<T> {
static std::string convert( T const& value ) {
return convertMyTypeToString( value );
}
};
2015-05-20 19:12:40 +02:00
}
```
## Catch::is_range specialisation
2018-02-01 20:29:18 +01:00
As a fallback, Catch attempts to detect if the type can be iterated
(`begin(T)` and `end(T)` are valid) and if it can be, it is stringified
as a range. For certain types this can lead to infinite recursion, so
it can be disabled by specializing `Catch::is_range` like so:
```cpp
namespace Catch {
template<>
struct is_range<T> {
static const bool value = false;
};
}
```
## Exceptions
By default all exceptions deriving from `std::exception` will be translated to strings by calling the `what()` method. For exception types that do not derive from `std::exception` - or if `what()` does not return a suitable string - use `CATCH_TRANSLATE_EXCEPTION`. This defines a function that takes your exception type, by reference, and returns a string. It can appear anywhere in the code - it doesn't have to be in the same translation unit. For example:
2019-04-27 19:50:05 +02:00
```cpp
CATCH_TRANSLATE_EXCEPTION( MyType const& ex ) {
return ex.message();
}
```
2019-04-21 19:32:20 +02:00
## Enums
> Introduced in Catch2 2.8.0.
2019-07-21 22:13:58 +02:00
2019-04-21 19:32:20 +02:00
Enums that already have a `<<` overload for `std::ostream` will convert to strings as expected.
If you only need to convert enums to strings for test reporting purposes you can provide a `StringMaker` specialisations as any other type.
However, as a convenience, Catch provides the `REGISTER_ENUM` helper macro that will generate the `StringMaker` specialiation for you with minimal code.
Simply provide it the (qualified) enum name, followed by all the enum values, and you're done!
E.g.
2019-04-27 19:50:05 +02:00
```cpp
2019-04-21 19:32:20 +02:00
enum class Fruits { Banana, Apple, Mango };
CATCH_REGISTER_ENUM( Fruits, Fruits::Banana, Fruits::Apple, Fruits::Mango )
2019-04-21 19:32:20 +02:00
TEST_CASE() {
REQUIRE( Fruits::Mango == Fruits::Apple );
}
```
... or if the enum is in a namespace:
2019-04-27 19:50:05 +02:00
```cpp
2019-04-21 19:32:20 +02:00
namespace Bikeshed {
enum class Colours { Red, Green, Blue };
}
// Important!: This macro must appear at top level scope - not inside a namespace
// You can fully qualify the names, or use a using if you prefer
CATCH_REGISTER_ENUM( Bikeshed::Colours,
Bikeshed::Colours::Red,
Bikeshed::Colours::Green,
2019-04-27 19:50:05 +02:00
Bikeshed::Colours::Blue )
2019-04-21 19:32:20 +02:00
TEST_CASE() {
REQUIRE( Bikeshed::Colours::Red == Bikeshed::Colours::Blue );
}
```
## Floating point precision
> [Introduced](https://github.com/catchorg/Catch2/issues/1614) in Catch2 2.8.0.
2019-07-21 22:13:58 +02:00
Catch provides a built-in `StringMaker` specialization for both `float`
2019-05-08 15:04:33 +02:00
and `double`. By default, it uses what we think is a reasonable precision,
but you can customize it by modifying the `precision` static variable
inside the `StringMaker` specialization, like so:
```cpp
Catch::StringMaker<float>::precision = 15;
const float testFloat1 = 1.12345678901234567899f;
const float testFloat2 = 1.12345678991234567899f;
REQUIRE(testFloat1 == testFloat2);
```
This assertion will fail and print out the `testFloat1` and `testFloat2`
to 15 decimal places.
2019-04-21 19:32:20 +02:00
2014-12-09 19:54:35 +01:00
---
[Home](Readme.md#top)