docs/tostring.md

   1 # String conversions
   2
   3 Catch needs to be able to convert types you use in assertions and logging expressions into strings (for logging and reporting purposes).
   4 Most built-in or std types are supported out of the box but there are three ways that you can tell Catch how to convert your own types (or other, third-party types) into strings.
   5
   6 ## operator << overload for std::ostream
   7
   8 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:
   9
  10 ```
  11 std::ostream& operator << ( std::ostream& os, T const& value ) {
  12         os << convertMyTypeToString( value );
  13         return os;
  14 }
  15 ```
  16
  17 (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).
  18
  19 You should put this function in the same namespace as your type and it has to be declared before including Catch's header.
  20
  21 ## Catch::toString overload
  22
  23 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 ```Catch::toString()``` for your type.
  24
  25 ```
  26 namespace Catch {
  27         std::string toString( T const& value ) {
  28                 return convertMyTypeToString( value );
  29         }
  30 }
  31 ```
  32
  33 Again ```T``` is your type and ```convertMyTypeToString``` is where you'll write whatever code is necessary to make your type printable. Note that the function must be in the Catch namespace, which itself must be in the global namespace and must be declared _before_ Catch's header is included.
  34
  35 **Please note that overloading `Catch::toString` is currently considered legacy and will not be supported in the next major version of Catch.**
  36
  37 ## Catch::StringMaker<T> specialisation
  38 Another way of telling Catch how to convert a type to string is specialising `Catch::StringMaker` template. This allows you to have separate way of stringifying types for Catch, than you have for writing it to a stream and also doesn't require you to declare it before including Catch's header.
  39
  40 ```
  41 namespace Catch {
  42         template<> struct StringMaker<T> {
  43         static std::string convert( T const& value ) {
  44                 return convertMyTypeToString( value );
  45         }
  46     };
  47 }
  48 ```
  49
  50 ## Exceptions
  51
  52 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:
  53
  54 ```
  55 CATCH_TRANSLATE_EXCEPTION( MyType& ex ) {
  56         return ex.message();
  57 }
  58 ```
  59
  60 ---
  61
  62 [Home](Readme.md)