1[/ 2 / Copyright (c) 2008 Eric Niebler 3 / 4 / Distributed under the Boost Software License, Version 1.0. (See accompanying 5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 /] 7 8[section:tips_n_tricks Tips 'N Tricks] 9 10Squeeze the most performance out of xpressive with these tips and tricks. 11 12[h2 Compile Patterns Once And Reuse Them] 13 14Compiling a regex (dynamic or static) is /far/ more expensive than executing a 15match or search. If you have the option, prefer to compile a pattern into 16a _basic_regex_ object once and reuse it rather than recreating it over 17and over. 18 19Since _basic_regex_ objects are not mutated by any of the regex algorithms, they 20are completely thread-safe once their initialization (and that of any grammars of 21which they are members) completes. The easiest way to reuse your patterns is 22to simply make your _basic_regex_ objects "static const". 23 24[h2 Reuse _match_results_ Objects] 25 26The _match_results_ object caches dynamically allocated memory. For this 27reason, it is far better to reuse the same _match_results_ object if you 28have to do many regex searches. 29 30Caveat: _match_results_ objects are not thread-safe, so don't go wild 31reusing them across threads. 32 33[h2 Prefer Algorithms That Take A _match_results_ Object] 34 35This is a corollary to the previous tip. If you are doing multiple searches, 36you should prefer the regex algorithms that accept a _match_results_ object 37over the ones that don't, and you should reuse the same _match_results_ object 38each time. If you don't provide a _match_results_ object, a temporary one 39will be created for you and discarded when the algorithm returns. Any 40memory cached in the object will be deallocated and will have to be reallocated 41the next time. 42 43[h2 Prefer Algorithms That Accept Iterator Ranges Over Null-Terminated Strings] 44 45xpressive provides overloads of the _regex_match_ and _regex_search_ 46algorithms that operate on C-style null-terminated strings. You should 47prefer the overloads that take iterator ranges. When you pass a 48null-terminated string to a regex algorithm, the end iterator is calculated 49immediately by calling `strlen`. If you already know the length of the string, 50you can avoid this overhead by calling the regex algorithms with a `[begin, end)` 51pair. 52 53[h2 Use Static Regexes] 54 55On average, static regexes execute about 10 to 15% faster than their 56dynamic counterparts. It's worth familiarizing yourself with the static 57regex dialect. 58 59[h2 Understand [^syntax_option_type::optimize]] 60 61The `optimize` flag tells the regex compiler to spend some extra time analyzing 62the pattern. It can cause some patterns to execute faster, but it increases 63the time to compile the pattern, and often increases the amount of memory 64consumed by the pattern. If you plan to reuse your pattern, `optimize` is 65usually a win. If you will only use the pattern once, don't use `optimize`. 66 67[h1 Common Pitfalls] 68 69Keep the following tips in mind to avoid stepping in potholes with xpressive. 70 71[h2 Create Grammars On A Single Thread] 72 73With static regexes, you can create grammars by nesting regexes inside one 74another. When compiling the outer regex, both the outer and inner regex objects, 75and all the regex objects to which they refer either directly or indirectly, are 76modified. For this reason, it's dangerous for global regex objects to participate 77in grammars. It's best to build regex grammars from a single thread. Once built, 78the resulting regex grammar can be executed from multiple threads without 79problems. 80 81[h2 Beware Nested Quantifiers] 82 83This is a pitfall common to many regular expression engines. Some patterns can 84cause exponentially bad performance. Often these patterns involve one quantified 85term nested withing another quantifier, such as `"(a*)*"`, although in many 86cases, the problem is harder to spot. Beware of patterns that have nested 87quantifiers. 88 89[endsect] 90