Boost.Regex: Configuration and setup

###  | # Boost.Regex ## Configuration and setup | ###

## Contents

Compiler setup
Locale and traits class selection
Linkage Options
Algorithm Selection
Algorithm Tuning

### Compiler setup.

You shouldn't need to do anything special to configure boost.regex for use with your compiler - the boost.config subsystem should already take care of it, if you do have problems (or you are using a particularly obscure compiler or platform) then boost.config has a configure script.

### Locale and traits class selection.

The following macros (see user.hpp) control how boost.regex interacts with the user's locale:

BOOST_REGEX_USE_C_LOCALE | Forces boost.regex to use the global C locale in its traits class support: this is now deprecated in favour of the C++ locale.
BOOST_REGEX_USE_CPP_LOCALE | Forces boost.regex to use std::locale in it's default traits class, regular expressions can then be imbued with an instance specific locale. This is the default behaviour on non-Windows platforms.
BOOST_REGEX_NO_W32 | Tells boost.regex not to use any Win32 API's even when available (implies BOOST_REGEX_USE_CPP_LOCALE unless BOOST_REGEX_USE_C_LOCALE is set).

### Linkage Options

BOOST_REGEX_DYN_LINK | For Microsoft and Borland C++ builds, this tells boost.regex that it should link to the dll build of the boost.regex. By default boost.regex will link to its static library build, even if the dynamic C runtime library is in use.
BOOST_REGEX_NO_LIB | For Microsoft and Borland C++ builds, this tells boost.regex that it should not automatically select the library to link to.

### Algorithm Selection

BOOST_REGEX_RECURSIVE | Tells boost.regex to use a stack-recursive matching algorithm. This is generally the fastest option (although there is very little in it), but can cause stack overflow in extreme cases, on Win32 this can be handled safely, but this is not the case on other platforms.
BOOST_REGEX_NON_RECURSIVE | Tells boost.regex to use a non-stack recursive matching algorithm, this can be slightly slower than the alternative, but is always safe no matter how pathological the regular expression. This is the default on non-Win32 platforms.

### Algorithm Tuning

The following option applies only if BOOST_REGEX_RECURSIVE is set.

BOOST_REGEX_HAS_MS_STACK_GUARD | Tells boost.regex that Microsoft style __try - __except blocks are supported, and can be used to safely trap stack overflow.

The following options apply only if BOOST_REGEX_NON_RECURSIVE is set.

BOOST_REGEX_BLOCKSIZE | In non-recursive mode, boost.regex uses largish blocks of memory to act as a stack for the state machine, the larger the block size then the fewer allocations that will take place. This defaults to 4096 bytes, which is large enough to match the vast majority of regular expressions without further allocations, however, you can choose smaller or larger values depending upon your platforms characteristics.
BOOST_REGEX_MAX_BLOCKS | Tells boost.regex how many blocks of size BOOST_REGEX_BLOCKSIZE it is permitted to use. If this value is exceeded then boost.regex will stop trying to find a match and throw a std::runtime_error. Defaults to 1024, don't forget to tweek this value if you alter BOOST_REGEX_BLOCKSIZE by much.
BOOST_REGEX_MAX_CACHE_BLOCKS | Tells boost.regex how many memory blocks to store in it's internal cache - memory blocks are taken from this cache rather than by calling ::operator new. Generally speeking this can be an order of magnitude faster than calling ::opertator new each time a memory block is required, but has the downside that boost.regex can end up caching a large chunk of memory (by default up to 16 blocks each of BOOST_REGEX_BLOCKSIZE size). If memory is tight then try defining this to 0 (disables all caching), or if that is too slow, then a value of 1 or 2, may be sufficient. On the other hand, on large multi-processor, multi-threaded systems, you may find that a higher value is in order.

Revised 23 June 2004

© Copyright John Maddock 1998- 2004

Use, modification and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)