Document order of returned matches

[mcpower]

The order of the returned matches from AhoCorasick methods is not explicitly documented. While the order can be inferred from the examples given, it is not fully clear for overlapping matches.

The overlapping example shows that the .end() of matches is strictly non-decreasing, but it does not show the behaviour when two matches end at the same index. I assume there are a few possibilities for what happens in this case:

• longest match (earliest start) first
• shortest match (latest start) first
• earliest PatternID first
• unspecified / random order

It would be helpful to document what happens in this case.

[BurntSushi]

Yeah I agree the docs could be improved here.

Even at the lowest layers of the public API, the order is specifically not mentioned. I'm wondering whether I did that intentionally.

(I believe the actual behavior is earliest PatternID first.)