Showed the difference between `map` and `and_then` with an example.

1 files changed, 17 insertions, 5 deletions

diff --git a/src/doc/book/error-handling.md b/src/doc/book/error-handling.md
index 9b1d16170b9..b5c0eabba9d 100644
--- a/src/doc/book/error-handling.md
+++ b/src/doc/book/error-handling.md
@@ -351,11 +351,21 @@ fn file_name(file_path: &str) -> Option<&str> {
 ```
 
 You might think that we could use the `map` combinator to reduce the case
-analysis, but its type doesn't quite fit. Namely, `map` takes a function that
-does something only with the inner value. The result of that function is then
-*always* [rewrapped with `Some`](#code-option-map). Instead, we need something
-like `map`, but which allows the caller to return another `Option`. Its generic
-implementation is even simpler than `map`:
+analysis, but its type doesn't quite fit...
+
+```rust
+fn file_path_ext(file_path: &str) -> Option<&str> {
+    file_name(file_path).map(|x| extension(x)) //Compilation error
+}
+```
+
+The `map` function here wraps the value returned by the `extension` function inside an `Option<_>` and since the `extension` function itself returns an `Option<&str>` the expression `file_name(file_path).map(|x| extension(x))` actually returns an `Option<Option<&str>>`.
+
+But since `file_path_ext` just returns `Option<&str>` (and not `Option<Option<&str>>`) we get a compilation error.
+
+The result of the function taken by map as input is *always* [rewrapped with `Some`](#code-option-map). Instead, we need something like `map`, but which allows the caller to return a `Option<_>` directly without wrapping it in another `Option<_>`.
+
+Its generic implementation is even simpler than `map`:
 
 ```rust
 fn and_then<F, T, A>(option: Option<T>, f: F) -> Option<A>
@@ -377,6 +387,8 @@ fn file_path_ext(file_path: &str) -> Option<&str> {
 }
 ```
 
+Side note: Since `and_then` essentially works like `map` but returns an `Option<_>` instead of an `Option<Option<_>>` it is known as `flatmap` in some other languages.
+
 The `Option` type has many other combinators [defined in the standard
 library][5]. It is a good idea to skim this list and familiarize
 yourself with what's available—they can often reduce case analysis