diff options
Diffstat (limited to 'docs/tostring.md')
-rw-r--r-- | docs/tostring.md | 67 |
1 files changed, 64 insertions, 3 deletions
diff --git a/docs/tostring.md b/docs/tostring.md index 933f2e61..156c895a 100644 --- a/docs/tostring.md +++ b/docs/tostring.md @@ -6,6 +6,9 @@ [Catch::StringMaker specialisation](#catchstringmaker-specialisation)<br> [Catch::is_range specialisation](#catchis_range-specialisation)<br> [Exceptions](#exceptions)<br> +[Enums](#enums)<br> +[Floating point precision](#floating-point-precision)<br> + 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. @@ -14,7 +17,7 @@ Most built-in or std types are supported out of the box but there are two ways t 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 std::ostream& operator << ( std::ostream& os, T const& value ) { os << convertMyTypeToString( value ); return os; @@ -28,7 +31,7 @@ You should put this function in the same namespace as your type, or the global n ## 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>`: -``` +```cpp namespace Catch { template<> struct StringMaker<T> { @@ -60,12 +63,70 @@ namespace Catch { 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: -``` +```cpp CATCH_TRANSLATE_EXCEPTION( MyType& ex ) { return ex.message(); } ``` +## Enums + +> Introduced in Catch 2.8.0. + +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. + +```cpp +enum class Fruits { Banana, Apple, Mango }; + +CATCH_REGISTER_ENUM( Fruits, Fruits::Banana, Fruits::Apple, Fruits::Mango ) + +TEST_CASE() { + REQUIRE( Fruits::Mango == Fruits::Apple ); +} +``` + +... or if the enum is in a namespace: +```cpp +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, + Bikeshed::Colours::Blue ) + +TEST_CASE() { + REQUIRE( Bikeshed::Colours::Red == Bikeshed::Colours::Blue ); +} +``` + +## Floating point precision + +> [Introduced](https://github.com/catchorg/Catch2/issues/1614) in Catch 2.8.0. + +Catch provides a built-in `StringMaker` specialization for both `float` +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. + --- [Home](Readme.md#top) |