summaryrefslogtreecommitdiff
path: root/docs/tostring.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/tostring.md')
-rw-r--r--docs/tostring.md132
1 files changed, 0 insertions, 132 deletions
diff --git a/docs/tostring.md b/docs/tostring.md
deleted file mode 100644
index 156c895a..00000000
--- a/docs/tostring.md
+++ /dev/null
@@ -1,132 +0,0 @@
-<a id="top"></a>
-# String conversions
-
-**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>
-[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.
-
-## 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
-std::ostream& operator << ( std::ostream& os, T const& value ) {
- os << convertMyTypeToString( value );
- return os;
-}
-```
-
-(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.
-
-## 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> {
- static std::string convert( T const& value ) {
- return convertMyTypeToString( value );
- }
- };
-}
-```
-
-## Catch::is_range specialisation
-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:
-
-```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)