boostorg/regex
1
0
Fork 1
mirror of https://github.com/boostorg/regex.git synced 2025-07-29 20:17:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

Document new build changes + standalone mode.

Browse Source
This commit is contained in:
jzmaddock
2021-01-25 11:52:44 +00:00
parent 4b4041c04d
commit 33c9ed2d42
7 changed files with 75 additions and 100 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
doc/configuration.qbk
View File

@ -17,6 +17,22 @@ or platform) then [@../../../config/index.html Boost.Config] has a configure scr
[endsect]
[section:standalone Use in Standalone Mode (without the rest of Boost)]
This library may now be used in "standalone" mode without the rest of the Boost C++ libraries,
in order to do this you must either:
* Have a C++17 compiler that supports `__has_include`, in this case if `<boost/config.hpp>` is *not* present
then the library will automoatically enter standalone mode. Or:
* Define BOOST_REGEX_STANDALONE when building.
The main difference between the 2 modes, is that when Boost.Config is present the library will automatically
configure itself around various compiler defects. In particular in order to use the library with exception support
turned off, you will either need a copy of Boost.Config in your include path, or else manually define BOOST_NO_EXCEPTIONS
when building.
[endsect]
[section:locale Locale and traits class selection]
The following macros (see [@../../../../boost/regex/user.hpp user.hpp]) control how Boost.Regex interacts with
@ -31,43 +47,11 @@ the user's locale:
[endsect]
[section:linkage Linkage Options]
[table
[[macro][description]]
[[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.]]
[[BOOST_REGEX_NO_FASTCALL][For Microsoft builds, this tells Boost.Regex to use the `__cdecl` calling convention rather than `__fastcall`. Useful if you want to use the same library from both managed and unmanaged code.]]
]
[endsect]
[section:algorithm Algorithm Selection]
[table
[[macro][description]]
[[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.]]
]
[endsect]
[section:tuning Algorithm Tuning]
The following option applies only if BOOST_REGEX_RECURSIVE is set.
[table
[[macro][description]]
[[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.
[table
[[macro][description]]
[[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_BLOCKSIZE][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 tweak 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

2
doc/html/boost_regex/configuration.html
View File

@ -30,8 +30,6 @@
<dt><span class="section"><a href="configuration/compiler.html">Compiler Setup</a></span></dt>
<dt><span class="section"><a href="configuration/locale.html">Locale and traits class
selection</a></span></dt>
<dt><span class="section"><a href="configuration/linkage.html">Linkage Options</a></span></dt>
<dt><span class="section"><a href="configuration/algorithm.html">Algorithm Selection</a></span></dt>
<dt><span class="section"><a href="configuration/tuning.html">Algorithm Tuning</a></span></dt>
</dl></div>
</div>

6
doc/html/boost_regex/configuration/locale.html
View File

@ -7,7 +7,7 @@
<link rel="home" href="../../index.html" title="Boost.Regex 5.1.4">
<link rel="up" href="../configuration.html" title="Configuration">
<link rel="prev" href="compiler.html" title="Compiler Setup">
<link rel="next" href="linkage.html" title="Linkage Options">
<link rel="next" href="tuning.html" title="Algorithm Tuning">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
@ -20,7 +20,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="compiler.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../configuration.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="linkage.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
<a accesskey="p" href="compiler.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../configuration.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tuning.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
@ -103,7 +103,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="compiler.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../configuration.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="linkage.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
<a accesskey="p" href="compiler.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../configuration.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tuning.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

56
doc/html/boost_regex/configuration/tuning.html
View File

@ -6,7 +6,7 @@
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Boost.Regex 5.1.4">
<link rel="up" href="../configuration.html" title="Configuration">
<link rel="prev" href="algorithm.html" title="Algorithm Selection">
<link rel="prev" href="locale.html" title="Locale and traits class selection">
<link rel="next" href="../install.html" title="Building and Installing the Library">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@ -20,49 +20,12 @@
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="algorithm.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../configuration.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../install.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
<a accesskey="p" href="locale.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../configuration.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../install.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_regex.configuration.tuning"></a><a class="link" href="tuning.html" title="Algorithm Tuning">Algorithm Tuning</a>
</h3></div></div></div>
<p>
The following option applies only if BOOST_REGEX_RECURSIVE is set.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th>
<p>
macro
</p>
</th>
<th>
<p>
description
</p>
</th>
</tr></thead>
<tbody><tr>
<td>
<p>
BOOST_REGEX_HAS_MS_STACK_GUARD
</p>
</td>
<td>
<p>
Tells Boost.Regex that Microsoft style __try - __except blocks
are supported, and can be used to safely trap stack overflow.
</p>
</td>
</tr></tbody>
</table></div>
<p>
The following options apply only if BOOST_REGEX_NON_RECURSIVE is set.
</p>
<div class="informaltable"><table class="table">
<colgroup>
<col>
@ -89,13 +52,12 @@
</td>
<td>
<p>
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 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.
</p>
</td>
</tr>
@ -150,7 +112,7 @@
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="algorithm.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../configuration.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../install.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
<a accesskey="p" href="locale.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../configuration.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../install.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>

36
doc/html/boost_regex/install.html
View File

@ -43,15 +43,39 @@
The library will encase all code inside namespace boost.
</p>
<p>
Unlike some other template libraries, this library consists of a mixture of
template code (in the headers) and static code and data (in cpp files). Consequently
it is necessary to build the library's support code into a library or archive
file before you can use it, instructions for specific platforms are as follows:
This is a header only library provided your compiler supports C++11 or later.
Support for C++03 compilers is still present, but is now deprecated and may
be removed without further notice!
</p>
<p>
The only people that still need to build the external libboost_regex library
are those that are either:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Using the library in C++03 mode, or,
</li>
<li class="listitem">
Using the deprecated POSIX C API's
</li>
</ul></div>
<p>
Further, this library may now be used in "standalone" mode without
the rest of the Boost C++ libraries, in order to do this you must either:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
Have a C++17 compiler that supports <code class="computeroutput"><span class="identifier">__has_include</span></code>,
in this case if <code class="computeroutput"><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">config</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code> is not present then the library will
automoatically enter standalone mode. Or:
</li>
<li class="listitem">
Define BOOST_REGEX_STANDALONE when building.
</li>
</ul></div>
<h5>
<a name="boost_regex.install.h0"></a>
<span class="phrase"><a name="boost_regex.install.building_with_bjam"></a></span><a class="link" href="install.html#boost_regex.install.building_with_bjam">Building
with bjam</a>
<span class="phrase"><a name="boost_regex.install.c_03_users_only_deprecated_build"></a></span><a class="link" href="install.html#boost_regex.install.c_03_users_only_deprecated_build"><span class="bold"><strong>C++03 users only (Deprecated)</strong></span> Building with bjam</a>
</h5>
<p>
This is now the preferred method for building and installing this library,

4
doc/html/index.html
View File

@ -44,8 +44,6 @@
<dt><span class="section"><a href="boost_regex/configuration/compiler.html">Compiler Setup</a></span></dt>
<dt><span class="section"><a href="boost_regex/configuration/locale.html">Locale and traits class
selection</a></span></dt>
<dt><span class="section"><a href="boost_regex/configuration/linkage.html">Linkage Options</a></span></dt>
<dt><span class="section"><a href="boost_regex/configuration/algorithm.html">Algorithm Selection</a></span></dt>
<dt><span class="section"><a href="boost_regex/configuration/tuning.html">Algorithm Tuning</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="boost_regex/install.html">Building and Installing the Library</a></span></dt>
@ -215,7 +213,7 @@
</p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"><p><small>Last revised: November 23, 2020 at 17:52:46 GMT</small></p></td>
<td align="left"><p><small>Last revised: January 25, 2021 at 11:08:05 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>

21
doc/install.qbk
View File

@ -20,13 +20,22 @@ process is the same as for all of boost; see the
The library will encase all code inside namespace boost.
Unlike some other template libraries, this library consists of a mixture of
template code (in the headers) and static code and data (in cpp files).
Consequently it is necessary to build the library's support code into a
library or archive file before you can use it, instructions for specific
platforms are as follows:
This is a header only library provided your compiler supports C++11 or later. Support for
C++03 compilers is still present, but is now deprecated and may be removed without further notice!
[h4 Building with bjam]
The only people that still need to build the external libboost_regex library are those that are either:
* Using the library in C++03 mode, or,
* Using the deprecated POSIX C API's
Further, this library may now be used in "standalone" mode without the rest of the Boost C++ libraries,
in order to do this you must either:
* Have a C++17 compiler that supports `__has_include`, in this case if `<boost/config.hpp>` is not present
then the library will automoatically enter standalone mode. Or:
* Define BOOST_REGEX_STANDALONE when building.
[h4 [*C++03 users only (Deprecated)] Building with bjam]
This is now the preferred method for building and installing this library,
please refer to the