Auto merge of rust-lang#407 - robinst:issue-406-document-beginning-of…

…-line-matching, r=BurntSushi

Add an example for `(?m)^` matching at end of text

Fixes rust-lang#406.

src/lib.rs

@@ -398,7 +398,7 @@ Notice that the `a+` matches either `a` or `A`, but the `b+` only matches
 `b`.
 
 Multi-line mode means `^` and `$` no longer match just at the beginning/end of
-the input:
+the input, but at the beginning/end of lines:
 
 ```
 # use regex::Regex;
@@ -407,6 +407,15 @@ let m = re.find("line one\nline 2\n").unwrap();
 assert_eq!(m.as_str(), "line 2");
 ```
 
+Note that `^` matches after new lines, even at the end of input:
+
+```
+# use regex::Regex;
+let re = Regex::new(r"(?m)^").unwrap();
+let m = re.find_iter("test\n").last().unwrap();
+assert_eq!((m.start(), m.end()), (5, 5));
+```
+
 Here is an example that uses an ASCII word boundary instead of a Unicode
 word boundary: