Squashed 'third_party/boostorg/utility/' content from commit ebe4429
Change-Id: I8e6ee78273db31df18f99d29034f855ccc064551
git-subtree-dir: third_party/boostorg/utility
git-subtree-split: ebe44296ca698e333a09e8268ea8ccedb3886c4d
diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2
new file mode 100644
index 0000000..dda8f39
--- /dev/null
+++ b/doc/Jamfile.v2
@@ -0,0 +1,127 @@
+
+# Copyright John Maddock 2005. 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)
+
+project : requirements
+ # Path for links to Boost:
+ <xsl:param>boost.root=../../../..
+
+ # Some general style settings:
+ <xsl:param>table.footnote.number.format=1
+ <xsl:param>footnote.number.format=1
+
+ # HTML options first:
+ # Use graphics not text for navigation:
+ <xsl:param>navig.graphics=1
+ # PDF Options:
+ # TOC Generation: this is needed for FOP-0.9 and later:
+ <xsl:param>fop1.extensions=0
+ <xsl:param>xep.extensions=1
+ # TOC generation: this is needed for FOP 0.2, but must not be set to zero for FOP-0.9!
+ <xsl:param>fop.extensions=0
+ # No indent on body text:
+ <xsl:param>body.start.indent=0pt
+ # Margin size:
+ <xsl:param>page.margin.inner=0.5in
+ # Margin size:
+ <xsl:param>page.margin.outer=0.5in
+ # Paper type = A4
+ <xsl:param>paper.type=A4
+ # Yes, we want graphics for admonishments:
+ <xsl:param>admon.graphics=1
+ # Set this one for PDF generation *only*:
+ # default pnd graphics are awful in PDF form,
+ # better use SVG's instead:
+ <format>pdf:<xsl:param>admon.graphics.extension=".svg"
+ <format>pdf:<xsl:param>admon.graphics.path=$(boost-images)/
+ <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/utility/doc/html
+;
+
+using quickbook ;
+
+path-constant boost-images : ../../../doc/src/images ;
+
+xml base_from_member : base_from_member.qbk ;
+boostbook standalone_base_from_member
+ :
+ base_from_member
+ :
+ # File name of HTML output:
+ <xsl:param>root.filename=base_from_member
+ # How far down we chunk nested sections, basically all of them:
+ <xsl:param>chunk.section.depth=0
+ # Don't put the first section on the same page as the TOC:
+ <xsl:param>chunk.first.sections=0
+ # How far down sections get TOC's
+ <xsl:param>toc.section.depth=1
+ # Max depth in each TOC:
+ <xsl:param>toc.max.depth=1
+ # How far down we go with TOC's
+ <xsl:param>generate.section.toc.level=1
+ ;
+
+xml compressed_pair : compressed_pair.qbk ;
+boostbook standalone_compressed_pair
+ :
+ compressed_pair
+ :
+ # File name of HTML output:
+ <xsl:param>root.filename=compressed_pair
+ # How far down we chunk nested sections, basically all of them:
+ <xsl:param>chunk.section.depth=0
+ # Don't put the first section on the same page as the TOC:
+ <xsl:param>chunk.first.sections=0
+ # How far down sections get TOC's
+ <xsl:param>toc.section.depth=1
+ # Max depth in each TOC:
+ <xsl:param>toc.max.depth=1
+ # How far down we go with TOC's
+ <xsl:param>generate.section.toc.level=1
+ ;
+
+xml declval : declval.qbk ;
+boostbook standalone_declval
+ :
+ declval
+ :
+ # File name of HTML output:
+ <xsl:param>root.filename=declval
+ # How far down we chunk nested sections, basically all of them:
+ <xsl:param>chunk.section.depth=0
+ # Don't put the first section on the same page as the TOC:
+ <xsl:param>chunk.first.sections=0
+ # How far down sections get TOC's
+ <xsl:param>toc.section.depth=1
+ # Max depth in each TOC:
+ <xsl:param>toc.max.depth=1
+ # How far down we go with TOC's
+ <xsl:param>generate.section.toc.level=1
+ ;
+
+xml string_ref : string_ref.qbk ;
+boostbook standalone_string_ref
+ :
+ string_ref
+ :
+ # File name of HTML output:
+ <xsl:param>root.filename=string_ref
+ # How far down we chunk nested sections, basically all of them:
+ <xsl:param>chunk.section.depth=0
+ # Don't put the first section on the same page as the TOC:
+ <xsl:param>chunk.first.sections=0
+ # How far down sections get TOC's
+ <xsl:param>toc.section.depth=1
+ # Max depth in each TOC:
+ <xsl:param>toc.max.depth=1
+ # How far down we go with TOC's
+ <xsl:param>generate.section.toc.level=1
+ ;
+
+###############################################################################
+alias boostdoc ;
+explicit boostdoc ;
+alias boostrelease :
+ standalone_base_from_member standalone_compressed_pair
+ standalone_declval standalone_string_ref ;
+explicit boostrelease ;
diff --git a/doc/base_from_member.qbk b/doc/base_from_member.qbk
new file mode 100644
index 0000000..9afd949
--- /dev/null
+++ b/doc/base_from_member.qbk
@@ -0,0 +1,363 @@
+[/
+ Copyright 2001, 2003, 2004, 2012 Daryle Walker.
+
+ Distributed under the Boost Software License, Version 1.0.
+
+ See accompanying file LICENSE_1_0.txt
+ or copy at http://boost.org/LICENSE_1_0.txt
+]
+
+[article Base_From_Member
+ [quickbook 1.5]
+ [authors [Walker, Daryle]]
+ [copyright 2001, 2003, 2004, 2012 Daryle Walker]
+ [license
+ Distributed under 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])
+ ]
+]
+
+[section Rationale]
+
+When developing a class, sometimes a base class needs to be initialized
+with a member of the current class. As a na\u00EFve example:
+
+ #include <streambuf> /* for std::streambuf */
+ #include <ostream> /* for std::ostream */
+
+ class fdoutbuf
+ : public std::streambuf
+ {
+ public:
+ explicit fdoutbuf( int fd );
+ //...
+ };
+
+ class fdostream
+ : public std::ostream
+ {
+ protected:
+ fdoutbuf buf;
+ public:
+ explicit fdostream( int fd )
+ : buf( fd ), std::ostream( &buf ) {}
+ //...
+ };
+
+This is undefined because C++'s initialization order mandates that the base
+class is initialized before the member it uses. [@http://www.moocat.org R.
+Samuel Klatchko] developed a way around this by using the initialization
+order in his favor. Base classes are intialized in order of declaration, so
+moving the desired member to another base class, that is initialized before
+the desired base class, can ensure proper initialization.
+
+A custom base class can be made for this idiom:
+
+ #include <streambuf> /* for std::streambuf */
+ #include <ostream> /* for std::ostream */
+
+ class fdoutbuf
+ : public std::streambuf
+ {
+ public:
+ explicit fdoutbuf( int fd );
+ //...
+ };
+
+ struct fdostream_pbase
+ {
+ fdoutbuf sbuffer;
+
+ explicit fdostream_pbase( int fd )
+ : sbuffer( fd ) {}
+ };
+
+ class fdostream
+ : private fdostream_pbase
+ , public std::ostream
+ {
+ typedef fdostream_pbase pbase_type;
+ typedef std::ostream base_type;
+
+ public:
+ explicit fdostream( int fd )
+ : pbase_type( fd ), base_type( &sbuffer ) {}
+ //...
+ };
+
+Other projects can use similar custom base classes. The technique is basic
+enough to make a template, with a sample template class in this library.
+The main template parameter is the type of the enclosed member. The
+template class has several (explicit) constructor member templates, which
+implicitly type the constructor arguments and pass them to the member. The
+template class uses implicit copy construction and assignment, cancelling
+them if the enclosed member is non-copyable.
+
+Manually coding a base class may be better if the construction and/or
+copying needs are too complex for the supplied template class, or if the
+compiler is not advanced enough to use it.
+
+Since base classes are unnamed, a class cannot have multiple (direct) base
+classes of the same type. The supplied template class has an extra template
+parameter, an integer, that exists solely to provide type differentiation.
+This parameter has a default value so a single use of a particular member
+type does not need to concern itself with the integer.
+
+[endsect]
+
+[section Synopsis]
+
+ #include <type_traits> /* exposition only */
+
+ #ifndef BOOST_BASE_FROM_MEMBER_MAX_ARITY
+ #define BOOST_BASE_FROM_MEMBER_MAX_ARITY 10
+ #endif
+
+ template < typename MemberType, int UniqueID = 0 >
+ class boost::base_from_member
+ {
+ protected:
+ MemberType member;
+
+ #if ``['C++11 is in use]``
+ template< typename ...T >
+ explicit constexpr base_from_member( T&& ...x )
+ noexcept( std::is_nothrow_constructible<MemberType, T...>::value );
+ #else
+ base_from_member();
+
+ template< typename T1 >
+ explicit base_from_member( T1 x1 );
+
+ template< typename T1, typename T2 >
+ base_from_member( T1 x1, T2 x2 );
+
+ //...
+
+ template< typename T1, typename T2, typename T3, typename T4,
+ typename T5, typename T6, typename T7, typename T8, typename T9,
+ typename T10 >
+ base_from_member( T1 x1, T2 x2, T3 x3, T4 x4, T5 x5, T6 x6, T7 x7,
+ T8 x8, T9 x9, T10 x10 );
+ #endif
+ };
+
+ template < typename MemberType, int UniqueID >
+ class base_from_member<MemberType&, UniqueID>
+ {
+ protected:
+ MemberType& member;
+
+ explicit constexpr base_from_member( MemberType& x )
+ noexcept;
+ };
+
+The class template has a first template parameter `MemberType` representing
+the type of the based-member. It has a last template parameter `UniqueID`,
+that is an `int`, to differentiate between multiple base classes that use
+the same based-member type. The last template parameter has a default value
+of zero if it is omitted. The class template has a protected data member
+called `member` that the derived class can use for later base classes (or
+itself).
+
+If the appropriate features of C++11 are present, there will be a single
+constructor template. It implements ['perfect forwarding] to the best
+constructor call of `member` (if any). The constructor template is marked
+both `constexpr` and `explicit`. The former will be ignored if the
+corresponding inner constructor call (of `member`) does not have the marker.
+The latter binds the other way; always taking effect, even when the inner
+constructor call does not have the marker. The constructor template
+propagates the `noexcept` status of the inner constructor call. (The
+constructor template has a trailing parameter with a default value that
+disables the template when its signature is too close to the signatures of
+the automatically-defined non-template copy- and/or move-constructors of
+`base_from_member`.)
+
+On earlier-standard compilers, there is a default constructor and several
+constructor member templates. These constructor templates can take as many
+arguments (currently up to ten) as possible and pass them to a constructor
+of the data member.
+
+A specialization for member references offers a single constructor taking
+a `MemberType&`, which is the only way to initialize a reference.
+
+Since C++ does not allow any way to explicitly state the template parameters
+of a templated constructor, make sure that the arguments are already close
+as possible to the actual type used in the data member's desired constructor.
+Explicit conversions may be necessary.
+
+The `BOOST_BASE_FROM_MEMBER_MAX_ARITY` macro constant specifies the maximum
+argument length for the constructor templates. The constant may be overridden
+if more (or less) argument configurations are needed. The constant may be
+read for code that is expandable like the class template and needs to
+maintain the same maximum size. (Example code would be a class that uses
+this class template as a base class for a member with a flexible set of
+constructors.) This constant is ignored when C++11 features are present.
+
+[endsect]
+
+[section Usage]
+
+With the starting example, the `fdoutbuf` sub-object needs to be
+encapsulated in a base class that is inheirited before `std::ostream`.
+
+ #include <boost/utility/base_from_member.hpp>
+
+ #include <streambuf> // for std::streambuf
+ #include <ostream> // for std::ostream
+
+ class fdoutbuf
+ : public std::streambuf
+ {
+ public:
+ explicit fdoutbuf( int fd );
+ //...
+ };
+
+ class fdostream
+ : private boost::base_from_member<fdoutbuf>
+ , public std::ostream
+ {
+ // Helper typedef's
+ typedef boost::base_from_member<fdoutbuf> pbase_type;
+ typedef std::ostream base_type;
+
+ public:
+ explicit fdostream( int fd )
+ : pbase_type( fd ), base_type( &member ){}
+ //...
+ };
+
+The base-from-member idiom is an implementation detail, so it should not
+be visible to the clients (or any derived classes) of `fdostream`. Due to
+the initialization order, the `fdoutbuf` sub-object will get initialized
+before the `std::ostream` sub-object does, making the former sub-object
+safe to use in the latter sub-object's construction. Since the `fdoutbuf`
+sub-object of the final type is the only sub-object with the name `member`
+that name can be used unqualified within the final class.
+
+[endsect]
+
+[section Example]
+
+The base-from-member class templates should commonly involve only one
+base-from-member sub-object, usually for attaching a stream-buffer to an
+I/O stream. The next example demonstrates how to use multiple
+base-from-member sub-objects and the resulting qualification issues.
+
+ #include <boost/utility/base_from_member.hpp>
+
+ #include <cstddef> /* for NULL */
+
+ struct an_int
+ {
+ int y;
+
+ an_int( float yf );
+ };
+
+ class switcher
+ {
+ public:
+ switcher();
+ switcher( double, int * );
+ //...
+ };
+
+ class flow_regulator
+ {
+ public:
+ flow_regulator( switcher &, switcher & );
+ //...
+ };
+
+ template < unsigned Size >
+ class fan
+ {
+ public:
+ explicit fan( switcher );
+ //...
+ };
+
+ class system
+ : private boost::base_from_member<an_int>
+ , private boost::base_from_member<switcher>
+ , private boost::base_from_member<switcher, 1>
+ , private boost::base_from_member<switcher, 2>
+ , protected flow_regulator
+ , public fan<6>
+ {
+ // Helper typedef's
+ typedef boost::base_from_member<an_int> pbase0_type;
+ typedef boost::base_from_member<switcher> pbase1_type;
+ typedef boost::base_from_member<switcher, 1> pbase2_type;
+ typedef boost::base_from_member<switcher, 2> pbase3_type;
+
+ typedef flow_regulator base1_type;
+ typedef fan<6> base2_type;
+
+ public:
+ system( double x );
+ //...
+ };
+
+ system::system( double x )
+ : pbase0_type( 0.2 )
+ , pbase1_type()
+ , pbase2_type( -16, &this->pbase0_type::member.y )
+ , pbase3_type( x, static_cast<int *>(NULL) )
+ , base1_type( pbase3_type::member, pbase1_type::member )
+ , base2_type( pbase2_type::member )
+ {
+ //...
+ }
+
+The final class has multiple sub-objects with the name `member`, so any
+use of that name needs qualification by a name of the appropriate base
+type. (Using `typedef`s ease mentioning the base types.) However, the fix
+introduces a new problem when a pointer is needed. Using the address
+operator with a sub-object qualified with its class's name results in a
+pointer-to-member (here, having a type of `an_int boost::base_from_member<
+an_int, 0> :: *`) instead of a pointer to the member (having a type of
+`an_int *`). The new problem is fixed by qualifying the sub-object with
+`this->` and is needed just for pointers, and not for references or values.
+
+There are some argument conversions in the initialization. The constructor
+argument for `pbase0_type` is converted from `double` to `float`. The first
+constructor argument for `pbase2_type` is converted from `int` to `double`.
+The second constructor argument for `pbase3_type` is a special case of
+necessary conversion; all forms of the null-pointer literal in C++ (except
+`nullptr` from C++11) also look like compile-time integral expressions, so
+C++ always interprets such code as an integer when it has overloads that can
+take either an integer or a pointer. The last conversion is necessary for the
+compiler to call a constructor form with the exact pointer type used in
+`switcher`'s constructor. (If C++11's `nullptr` is used, it still needs a
+conversion if multiple pointer types can be accepted in a constructor call
+but `std::nullptr_t` cannot.)
+
+[endsect]
+
+[section Acknowledgments]
+
+* [@http://www.boost.org/people/ed_brey.htm Ed Brey] suggested some interface
+changes.
+
+* [@http://www.moocat.org R. Samuel Klatchko] ([@mailto:rsk@moocat.org
+rsk@moocat.org], [@mailto:rsk@brightmail.com rsk@brightmail.com]) invented
+the idiom of how to use a class member for initializing a base class.
+
+* [@http://www.boost.org/people/dietmar_kuehl.htm Dietmar Kuehl] popularized the
+ base-from-member idiom in his [@http://www.informatik.uni-konstanz.de/~kuehl/c++/iostream/
+ IOStream example classes].
+
+* Jonathan Turkanis supplied an implementation of generating the constructor
+templates that can be controlled and automated with macros. The
+implementation uses the [@../../../preprocessor/index.html Preprocessor library].
+
+* [@http://www.boost.org/people/daryle_walker.html">Daryle Walker] started the
+library. Contributed the test file [@../../base_from_member_test.cpp
+base_from_member_test.cpp].
+
+[endsect]
+
diff --git a/doc/compressed_pair.qbk b/doc/compressed_pair.qbk
new file mode 100644
index 0000000..eac4266
--- /dev/null
+++ b/doc/compressed_pair.qbk
@@ -0,0 +1,99 @@
+[/
+ Copyright 2000 Beman Dawes & John Maddock.
+
+ Distributed under the Boost Software License, Version 1.0.
+
+ See accompanying file LICENSE_1_0.txt
+ or copy at http://boost.org/LICENSE_1_0.txt
+]
+
+[article Compressed_Pair
+ [quickbook 1.5]
+ [authors [Cleary, Steve]]
+ [authors [Dawes, Beman]]
+ [authors [Hinnant, Howard]]
+ [authors [Maddock, John]]
+ [copyright 2000 Steve Cleary, Beman Dawes, Howard Hinnant & John Maddock]
+ [license
+ Distributed under 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])
+ ]
+]
+
+[section Overview]
+
+All of the contents of `<boost/compressed_pair.hpp>` are defined inside
+`namespace boost`.
+
+The class `compressed_pair` is very similar to `std::pair`, but if either of
+the template arguments are empty classes, then the ['empty base-class
+optimisation] is applied to compress the size of the pair.
+
+[endsect]
+
+[section Synopsis]
+
+ template <class T1, class T2>
+ class compressed_pair
+ {
+ public:
+ typedef T1 first_type;
+ typedef T2 second_type;
+ typedef typename call_traits<first_type>::param_type first_param_type;
+ typedef typename call_traits<second_type>::param_type second_param_type;
+ typedef typename call_traits<first_type>::reference first_reference;
+ typedef typename call_traits<second_type>::reference second_reference;
+ typedef typename call_traits<first_type>::const_reference first_const_reference;
+ typedef typename call_traits<second_type>::const_reference second_const_reference;
+
+ compressed_pair() : base() {}
+ compressed_pair(first_param_type x, second_param_type y);
+ explicit compressed_pair(first_param_type x);
+ explicit compressed_pair(second_param_type y);
+
+ compressed_pair& operator=(const compressed_pair&);
+
+ first_reference first();
+ first_const_reference first() const;
+
+ second_reference second();
+ second_const_reference second() const;
+
+ void swap(compressed_pair& y);
+ };
+
+The two members of the pair can be accessed using the member functions
+`first()` and `second()`. Note that not all member functions can be
+instantiated for all template parameter types. In particular
+`compressed_pair` can be instantiated for reference and array types,
+however in these cases the range of constructors that can be used are
+limited. If types `T1` and `T2` are the same type, then there is only
+one version of the single-argument constructor, and this constructor
+initialises both values in the pair to the passed value.
+
+Note that if either member is a POD type, then that member is not
+zero-initialized by the `compressed_pair` default constructor: it's up
+to you to supply an initial value for these types if you want them to have
+a default value.
+
+Note that `compressed_pair` can not be instantiated if either of the
+template arguments is a union type, unless there is compiler support for
+`boost::is_union`, or if `boost::is_union` is specialised for the union
+type.
+
+Finally, a word of caution for Visual C++ 6 users: if either argument is an
+empty type, then assigning to that member will produce memory corruption,
+unless the empty type has a "do nothing" assignment operator defined. This
+is due to a bug in the way VC6 generates implicit assignment operators.
+
+[endsect]
+
+[section Acknowledgments]
+
+Based on contributions by Steve Cleary, Beman Dawes, Howard Hinnant and
+John Maddock.
+
+Maintained by [@mailto:john@johnmaddock.co.uk John Maddock].
+
+[endsect]
diff --git a/doc/declval.qbk b/doc/declval.qbk
new file mode 100644
index 0000000..910aaf6
--- /dev/null
+++ b/doc/declval.qbk
@@ -0,0 +1,114 @@
+[/
+ / Copyright (c) 2008 Howard Hinnant
+ / Copyright (c) 2009-20012 Vicente J. Botet Escriba
+ /
+ / Distributed under 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)
+ /]
+
+[article Declval
+ [quickbook 1.5]
+ [authors [Hinnant, Howard]]
+ [authors [Botet Escriba, Vicente J.]]
+ [copyright 2008 Howard Hinnant]
+ [copyright 2009-2012 Vicente J. Botet Escriba]
+ [license
+ Distributed under 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])
+ ]
+]
+
+[/===============]
+[section Overview]
+[/===============]
+
+The motivation for `declval` was introduced in [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2958.html#Value N2958:
+Moving Swap Forward]. Here follows a rewording of this chapter.
+
+With the provision of decltype, late-specified return types, and default template-arguments for function templates a
+new generation of SFINAE patterns will emerge to at least partially compensate the lack of concepts on the C++0x timescale.
+Using this technique, it is sometimes necessary to obtain an object of a known type in a non-using context, e.g. given the declaration
+
+ template<class T>
+ T&& declval(); // not used
+
+as part of the function template declaration
+
+ template<class To, class From>
+ decltype(static_cast<To>(declval<From>())) convert(From&&);
+
+or as part of a class template definition
+
+ template<class> class result_of;
+
+ template<class Fn, class... ArgTypes>
+ struct result_of<Fn(ArgTypes...)>
+ {
+ typedef decltype(declval<Fn>()(declval<ArgTypes>()...)) type;
+ };
+
+The role of the function template declval() is a transformation of a type T into a value without using or evaluating this function.
+The name is supposed to direct the reader's attention to the fact that the expression `declval<T>()` is an lvalue if and only if
+T is an lvalue-reference, otherwise an rvalue. To extend the domain of this function we can do a bit better by changing its declaration to
+
+ template<class T>
+ typename std::add_rvalue_reference<T>::type declval(); // not used
+
+which ensures that we can also use cv void as template parameter. The careful reader might have noticed that `declval()`
+already exists under the name create() as part of the definition of the semantics of the type trait is_convertible in the C++0x standard.
+
+The provision of a new library component that allows the production of values in unevaluated expressions is considered
+important to realize constrained templates in C++0x where concepts are not available.
+This extremely light-weight function is expected to be part of the daily tool-box of the C++0x programmer.
+
+[endsect]
+
+
+[/=================]
+[section:reference Reference ]
+[/=================]
+
+`#include <boost/utility/declval.hpp>`
+
+ namespace boost {
+
+ template <typename T>
+ typename add_rvalue_reference<T>::type declval() noexcept; // as unevaluated operand
+
+ } // namespace boost
+
+
+The library provides the function template declval to simplify the definition of expressions which occur as unevaluated operands.
+
+ template <typename T>
+ typename add_rvalue_reference<T>::type declval();
+
+[*Remarks:] If this function is used, the program is ill-formed.
+
+[*Remarks:] The template parameter T of declval may be an incomplete type.
+
+[*Example:]
+
+ template <class To, class From>
+ decltype(static_cast<To>(declval<From>())) convert(From&&);
+
+Declares a function template convert which only participates in overloading if the type From can be explicitly converted to type To.
+
+[endsect]
+
+[/===============]
+[section History]
+[/===============]
+
+[heading boost 1.50]
+
+Fixes:
+
+* [@http://svn.boost.org/trac/boost/ticket/6570 #6570] Adding noexcept to boost::declval.
+
+[endsect]
+
+
+
+
diff --git a/doc/string_ref.qbk b/doc/string_ref.qbk
new file mode 100644
index 0000000..4c6fc79
--- /dev/null
+++ b/doc/string_ref.qbk
@@ -0,0 +1,167 @@
+[/
+ / Copyright (c) 2012 Marshall Clow
+ /
+ / Distributed under 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)
+ /]
+
+[article String_Ref
+ [quickbook 1.5]
+ [authors [Clow, Marshall]]
+ [copyright 2012 Marshall Clow]
+ [license
+ Distributed under 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])
+ ]
+]
+
+[/===============]
+[section Overview]
+[/===============]
+
+Boost.StringRef is an implementation of Jeffrey Yaskin's [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3442.html N3442:
+string_ref: a non-owning reference to a string].
+
+When you are parsing/processing strings from some external source, frequently you want to pass a piece of text to a procedure for specialized processing. The canonical way to do this is as a `std::string`, but that has certain drawbacks:
+
+1) If you are processing a buffer of text (say a HTTP response or the contents of a file), then you have to create the string from the text you want to pass, which involves memory allocation and copying of data.
+
+2) if a routine receives a constant `std::string` and wants to pass a portion of that string to another routine, then it must create a new string of that substring.
+
+3) A routine receives a constant `std::string` and wants to return a portion of the string, then it must create a new string to return.
+
+`string_ref` is designed to solve these efficiency problems. A `string_ref` is a read-only reference to a contiguous sequence of characters, and provides much of the functionality of `std::string`. A `string_ref` is cheap to create, copy and pass by value, because it does not actually own the storage that it points to.
+
+A `string_ref` is implemented as a small struct that contains a pointer to the start of the character data and a count. A `string_ref` is cheap to create and cheap to copy.
+
+`string_ref` acts as a container; it includes all the methods that you would expect in a container, including iteration support, `operator []`, `at` and `size`. It can be used with any of the iterator-based algorithms in the STL - as long as you don't need to change the underlying data (`sort` and `remove`, for example, will not work)
+
+Besides generic container functionality, `string_ref` provides a subset of the interface of `std::string`. This makes it easy to replace parameters of type `const std::string &` with `boost::string_ref`. Like `std::string`, `string_ref` has a static member variable named `npos` to denote the result of failed searches, and to mean "the end".
+
+Because a `string_ref` does not own the data that it "points to", it introduces lifetime issues into code that uses it. The programmer must ensure that the data that a `string_ref` refers to exists as long as the `string_ref` does.
+
+[endsect]
+
+
+[/===============]
+[section Examples]
+[/===============]
+
+Integrating `string_ref` into your code is fairly simple. Wherever you pass a `const std::string &` or `std::string` as a parameter, that's a candidate for passing a `boost::string_ref`.
+
+ std::string extract_part ( const std::string &bar ) {
+ return bar.substr ( 2, 3 );
+ }
+
+ if ( extract_part ( "ABCDEFG" ).front() == 'C' ) { /* do something */ }
+
+Let's figure out what happens in this (contrived) example.
+
+First, a temporary string is created from the string literal `"ABCDEFG"`, and it is passed (by reference) to the routine `extract_part`. Then a second string is created in the call `std::string::substr` and returned to `extract_part` (this copy may be elided by RVO). Then `extract_part` returns that string back to the caller (again this copy may be elided). The first temporary string is deallocated, and `front` is called on the second string, and then it is deallocated as well.
+
+Two `std::string`s are created, and two copy operations. That's (potentially) four memory allocations and deallocations, and the associated copying of data.
+
+Now let's look at the same code with `string_ref`:
+
+ boost::string_ref extract_part ( boost::string_ref bar ) {
+ return bar.substr ( 2, 3 );
+ }
+
+ if ( extract_part ( "ABCDEFG" ).front() == "C" ) { /* do something */ }
+
+No memory allocations. No copying of character data. No changes to the code other than the types. There are two `string_ref`s created, and two `string_ref`s copied, but those are cheap operations.
+
+[endsect]
+
+
+[/=================]
+[section:reference Reference ]
+[/=================]
+
+The header file "string_ref.hpp" defines a template `boost::basic_string_ref`, and four specializations - for `char` / `wchar_t` / `char16_t` / `char32_t` .
+
+`#include <boost/utility/string_ref.hpp>`
+
+Construction and copying:
+
+ BOOST_CONSTEXPR basic_string_ref (); // Constructs an empty string_ref
+ BOOST_CONSTEXPR basic_string_ref(const charT* str); // Constructs from a NULL-terminated string
+ BOOST_CONSTEXPR basic_string_ref(const charT* str, size_type len); // Constructs from a pointer, length pair
+ template<typename Allocator>
+ basic_string_ref(const std::basic_string<charT, traits, Allocator>& str); // Constructs from a std::string
+ basic_string_ref (const basic_string_ref &rhs);
+ basic_string_ref& operator=(const basic_string_ref &rhs);
+
+`string_ref` does not define a move constructor nor a move-assignment operator because copying a `string_ref` is just a cheap as moving one.
+
+Basic container-like functions:
+
+ BOOST_CONSTEXPR size_type size() const ;
+ BOOST_CONSTEXPR size_type length() const ;
+ BOOST_CONSTEXPR size_type max_size() const ;
+ BOOST_CONSTEXPR bool empty() const ;
+
+ // All iterators are const_iterators
+ BOOST_CONSTEXPR const_iterator begin() const ;
+ BOOST_CONSTEXPR const_iterator cbegin() const ;
+ BOOST_CONSTEXPR const_iterator end() const ;
+ BOOST_CONSTEXPR const_iterator cend() const ;
+ const_reverse_iterator rbegin() const ;
+ const_reverse_iterator crbegin() const ;
+ const_reverse_iterator rend() const ;
+ const_reverse_iterator crend() const ;
+
+Access to the individual elements (all of which are const):
+
+ BOOST_CONSTEXPR const charT& operator[](size_type pos) const ;
+ const charT& at(size_t pos) const ;
+ BOOST_CONSTEXPR const charT& front() const ;
+ BOOST_CONSTEXPR const charT& back() const ;
+ BOOST_CONSTEXPR const charT* data() const ;
+
+Modifying the `string_ref` (but not the underlying data):
+
+ void clear();
+ void remove_prefix(size_type n);
+ void remove_suffix(size_type n);
+
+Searching:
+
+ size_type find(basic_string_ref s) const ;
+ size_type find(charT c) const ;
+ size_type rfind(basic_string_ref s) const ;
+ size_type rfind(charT c) const ;
+ size_type find_first_of(charT c) const ;
+ size_type find_last_of (charT c) const ;
+
+ size_type find_first_of(basic_string_ref s) const ;
+ size_type find_last_of(basic_string_ref s) const ;
+ size_type find_first_not_of(basic_string_ref s) const ;
+ size_type find_first_not_of(charT c) const ;
+ size_type find_last_not_of(basic_string_ref s) const ;
+ size_type find_last_not_of(charT c) const ;
+
+String-like operations:
+
+ BOOST_CONSTEXPR basic_string_ref substr(size_type pos, size_type n=npos) const ; // Creates a new string_ref
+ bool starts_with(charT c) const ;
+ bool starts_with(basic_string_ref x) const ;
+ bool ends_with(charT c) const ;
+ bool ends_with(basic_string_ref x) const ;
+
+[endsect]
+
+[/===============]
+[section History]
+[/===============]
+
+[heading boost 1.53]
+* Introduced
+
+
+[endsect]
+
+
+
+