X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=folly%2Fdocs%2FConv.md;h=7156c11607218fa44cb87540dfdb72f08c351b95;hb=9783dc4e7cfa938f1c33666ec0a31c204dff60ed;hp=8d285e9dff3e9b64dc9a60041af9f2d3d227c54a;hpb=ad2f228ab1359952d37acdc4f3032e1405cca221;p=folly.git

diff --git a/folly/docs/Conv.md b/folly/docs/Conv.md
index 8d285e9d..7156c116 100644
--- a/folly/docs/Conv.md
+++ b/folly/docs/Conv.md
@@ -215,3 +215,31 @@ is returned, which can be tested for as follows:
       // string could not be parsed
     }
 ```
+
+#### Non-throwing interfaces
+
+`tryTo<T>` is the non-throwing variant of `to<T>`. It returns
+an `Expected<T, ConversionCode>`. You can think of `Expected`
+as like an `Optional<T>`, but if the conversion failed, `Expected`
+stores an error code instead of a `T`.
+
+`tryTo<T>` has similar performance as `to<T>` when the
+conversion is successful. On the error path, you can expect
+`tryTo<T>` to be roughly three orders of magnitude faster than
+the throwing `to<T>` and to completely avoid any lock contention
+arising from stack unwinding.
+
+Here is how to use non-throwing conversions:
+
+``` Cpp
+    auto t1 = tryTo<int>(str);
+    if (t1.hasValue()) {
+      use(t1.value());
+    }
+```
+
+`Expected` has a composability feature to make the above pattern simpler.
+
+``` Cpp
+    tryTo<int>(str).then([](int i) { use(i); });
+```