RegexBuilder should document that it does not incorporate flags into string-representation

[lukaslueg]

AFAICS regex::RegexBuilder does not incorporate flags into the string representation of the final regex.

let re = regex::RegexBuilder::new("foo").case_insensitive(true).compile().unwrap();
assert_eq!(re.as_str(), "(?i)foo");

panics because "foo" != "(?i)foo".

Am I confused about something here? Otherwise this should at least be documented :-)

[BurntSushi]

The string representation is the exact pattern given. The docs on the Display impl and as_str method say:

Shows the original regular expression.

How can the documentation be improved?

[lukaslueg]

I was under the impression that the string representation would by equivalent to the pattern and the flags set on RegexBuilder. That is, given ::new('foo') and .case_insensitive(true), the string representation is (?i)foo.

[BurntSushi]

Right, but it's not. I'm asking: how might the docs be improved so that you don't get that impression?

[lukaslueg]

Maybe a note in RegexBuilder::compile():

Consume the builder and compile the regular expression.
Note that the resulting `Regex::as_str()` returns the verbatim pattern given to `RegexBuilder::new()` without incorporating the flags set thereafter.