From bffc8eae34945e2ff31811829c14acb0eb73aba1 Mon Sep 17 00:00:00 2001
From: Ryan Haining <rhainin1@binghamton.edu>
Date: Fri, 14 Nov 2014 12:50:42 -0500
Subject: [PATCH] creates printabletypes.md to describe output

My findings after a morning of digging through the source.
---
 docs/printabletypes.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 docs/printabletypes.md

diff --git a/docs/printabletypes.md b/docs/printabletypes.md
new file mode 100644
index 00000000..dca4c8cd
--- /dev/null
+++ b/docs/printabletypes.md
@@ -0,0 +1,40 @@
+# Making Types Printable
+
+Catch is capable of using user defined print functions and overloads.
+
+## Using ostreams
+
+By default, catch will attempt to display types using an ostream overload is available.
+
+```c++
+std::ostream& operator<<(std::ostream&, MySpecialType const&);
+```
+
+## using toString
+If you don't want your type to work with ostreams, or Catch is unable to find the 
+overload you provide, you may alternatively overload `Catch::toString`.  The overload 
+must appear **above** the include of `catch.hpp`.  For example, if I want to provide
+a print functionality for `std::pair<int, char>` in my test, the top of my test file
+would look like this:
+
+```c++
+#include <string>
+#include <sstream>
+#include <utility>
+
+namespace Catch {
+std::string toString(std::pair<int, char> const p) {
+    std::ostringstream oss;
+    oss << '{' << p.first << ", " << p.second << '}';
+    return oss.str();
+}
+}
+
+#include "catch.hpp"
+```
+Note that the former approach is preferred, and the latter is more error-prone
+due to possible typos when typing `Catch` or `toString`
+
+## Default output
+
+If neither of the two conditions has been met, catch will output `{?}` by default.