The Boost C++ LibrariesThe Boost C++ Libraries
Documentation for some libraries is available in alternative formats:
HTML (tarred, gzipped)PDFUnix man pagesDocBookXSL Formatting ObjectsLibraries Listed AlphabeticallyAny -
Safe, generic container for single values of different value types
, from Kevlin Henney.Array - STL compliant container wrapper for arrays of constant size, from Nicolai Josuttis.Bind - Generalized binders for function/object/pointers and member functions, from Peter Dimov.CRC - Cyclic Redundancy Code, from Daryle Walker.Call Traits - Defines types for passing parameters, from John Maddock and Howard Hinnant.Compatibility - Help for non-conforming standard libraries, from Ralf Grosse-Kunstleve and Jens Maurer.Compose - Functional composition adapters for the STL, from Nicolai Josuttis.Compressed Pair - Empty member optimization, from John Maddock and Howard Hinnant.Concept Check - Tools for generic programming, from Jeremy Siek.Config - Helps boost library developers adapt to compiler idiosyncrasies; not intended for library users, from John Maddock, Beman Dawes, and Vesa Karvonen.Conversion - Numeric, polymorphic, and lexical casts, from Dave Abrahams and Kevlin Henney.Date Time - A set of facilities to ease programming with dates and times.
, from Jeff Garland.Dynamic Bitset - A runtime sized version of std::bitset, from Jeremy Siek and Chuck Allison.Filesystem - Portable paths, iteration over directories, and other useful filesystem operations, from Beman Dawes.Format - Type-safe 'printf-like' format operations, from Samuel Krempp.Function - Function object wrappers for deferred calls or callbacks, from Douglas Gregor.Functional - Enhanced function object adaptors, from Mark Rodgers.Graph - Generic graph components and algorithms, from Jeremy Siek and University of Notre Dame Team.I/O State Savers - Save I/O state to prevent jumbled data, from Daryle Walker.Integer - Headers to ease dealing with integral types, from various authors.Interval - Extends the usual arithmetic functions to mathematical intervals, from Guillaume Melquiond, Hervé Brönnimann, and Sylvain Pion.Iterator Adaptors - Adapt a base type into a standard conforming iterator, from Dave Abrahams, Jeremy Siek, and John Potter.Lambda - Define small unnamed function objects at the actual call site, and more, from Jaakko Järvi.MPL - Template metaprogramming framework of compile-time algorithms, sequences and metafunction classes, from Aleksey Gurtovoy.Math - Several contributions in the domain of mathematics, from various authors.Math/Common Factor - Greatest common divisor and least common multiple, from Daryle Walker.Math/Octonion - Octonions, from Hubert Holin.Math/Quaternion - Quaternions, from Hubert Holin.Math/Special Functions - Mathematical special functions such as atanh, sinc, and sinhc, from Hubert Holin.Mem_fn - Generalized binders for member functions, from Peter Dimov.Multi Array - Multidimensional containers and adaptors for arrays of contiguous data, from Ron Garcia.Operators - Templates ease arithmetic classes and iterators, from Dave Abrahams and Jeremy Siek.Optional - Discriminated-union wrapper for optional values, from Fernando Cacciola.Pool - Memory pool management, from Steve Cleary.Preprocessor - Preprocessor metaprogramming tools including repetition and recursion, from Vesa Karvonen and Paul Mensonides.Program_options -
Facilities to obtain configuration data from command line, config files
and other sources, from Vladimir Prus.Property Map - Concepts defining interfaces which map key objects to value objects, from Jeremy Siek.Python - Reflects C++ classes and functions into Python, from Dave Abrahams.Random - A complete system for random number generation, from Jens Maurer.Rational - A rational number class, from Paul Moore.Ref - A utility library for passing references to generic functions, from Jaakko Järvi, Peter Dimov, Douglas Gregor, and Dave Abrahams.Regex - Regular expression library, from John Maddock.Serialization - Serialization of C++ objects for persistence and marshalling, from Robert Ramey.Signals - Managed signals & slots callback implementation, from Douglas Gregor.Smart Pointer - Five smart pointer class templates, from Greg Colvin, Beman Dawes, Peter Dimov, and Darin Adler.Spirit - LL parser framework represents parsers directly as EBNF grammars in inlined C++, from Joel de Guzman and team .Static Assert - Static assertions (compile time assertions), from John Maddock.String Algorithms -
A set of generic string-related algorithms and utilities
, from Pavol Droba.Test - Support for simple program testing, full unit testing, and for program execution monitoring, from Gennadiy Rozental.Threads - Portable C++ multi-threading, from William Kempf.Timer - Event timer, progress timer, and progress display classes, from Beman Dawes.Tokenizer - Break of a string or other character sequence into a series of tokens, from John Bandela.Tribool - Three-state boolean type, from Douglas Gregor.Tuple - Ease definition of functions returning multiple values, and more, from Jaakko Järvi.Type Traits - Templates for fundamental properties of types, from John Maddock, Steve Cleary, and others .Utility - Class noncopyable plus checked_delete, checked_array_delete, next, prior function templates, plus base-from-member idiom, from Dave Abrahams and others .Variant - Safe, generic, stack-based discriminated union container, from Eric Friedman and Itay Maman.uBLAS - Basic linear algebra for dense, packed and sparse matrices, from Joerg Walter and Mathias Koch.Libraries Listed by Category
String and text processing
Format - Type-safe 'printf-like' format operations, from Samuel Krempp.Regex - Regular expression library, from John Maddock.String Algorithms -
A set of generic string-related algorithms and utilities
, from Pavol Droba.Tokenizer - Break of a string or other character sequence into a series of tokens, from John Bandela.
Containers
Array - STL compliant container wrapper for arrays of constant size, from Nicolai Josuttis.Dynamic Bitset - A runtime sized version of std::bitset, from Jeremy Siek and Chuck Allison.Graph - Generic graph components and algorithms, from Jeremy Siek and University of Notre Dame Team.Multi Array - Multidimensional containers and adaptors for arrays of contiguous data, from Ron Garcia.Property Map - Concepts defining interfaces which map key objects to value objects, from Jeremy Siek.Variant - Safe, generic, stack-based discriminated union container, from Eric Friedman and Itay Maman.
Iterators
Graph - Generic graph components and algorithms, from Jeremy Siek and University of Notre Dame Team.Iterator Adaptors - Adapt a base type into a standard conforming iterator, from Dave Abrahams, Jeremy Siek, and John Potter.Operators - Templates ease arithmetic classes and iterators, from Dave Abrahams and Jeremy Siek.Tokenizer - Break of a string or other character sequence into a series of tokens, from John Bandela.
Algorithms
Graph - Generic graph components and algorithms, from Jeremy Siek and University of Notre Dame Team.Utility - Class noncopyable plus checked_delete, checked_array_delete, next, prior function templates, plus base-from-member idiom, from Dave Abrahams and others .
Function objects and higher-order programming
Bind - Generalized binders for function/object/pointers and member functions, from Peter Dimov.Compose - Functional composition adapters for the STL, from Nicolai Josuttis.Function - Function object wrappers for deferred calls or callbacks, from Douglas Gregor.Functional - Enhanced function object adaptors, from Mark Rodgers.Lambda - Define small unnamed function objects at the actual call site, and more, from Jaakko Järvi.Mem_fn - Generalized binders for member functions, from Peter Dimov.Ref - A utility library for passing references to generic functions, from Jaakko Järvi, Peter Dimov, Douglas Gregor, and Dave Abrahams.Signals - Managed signals & slots callback implementation, from Douglas Gregor.
Generic programming
Call Traits - Defines types for passing parameters, from John Maddock and Howard Hinnant.Concept Check - Tools for generic programming, from Jeremy Siek.Operators - Templates ease arithmetic classes and iterators, from Dave Abrahams and Jeremy Siek.Property Map - Concepts defining interfaces which map key objects to value objects, from Jeremy Siek.Static Assert - Static assertions (compile time assertions), from John Maddock.Type Traits - Templates for fundamental properties of types, from John Maddock, Steve Cleary, and others .
Template metaprogramming
MPL - Template metaprogramming framework of compile-time algorithms, sequences and metafunction classes, from Aleksey Gurtovoy.Static Assert - Static assertions (compile time assertions), from John Maddock.Type Traits - Templates for fundamental properties of types, from John Maddock, Steve Cleary, and others .
Preprocessor metaprogramming
Preprocessor - Preprocessor metaprogramming tools including repetition and recursion, from Vesa Karvonen and Paul Mensonides.
Concurrent programming
Threads - Portable C++ multi-threading, from William Kempf.
Math and numerics
Integer - Headers to ease dealing with integral types, from various authors.Interval - Extends the usual arithmetic functions to mathematical intervals, from Guillaume Melquiond, Hervé Brönnimann, and Sylvain Pion.Math - Several contributions in the domain of mathematics, from various authors.Math/Common Factor - Greatest common divisor and least common multiple, from Daryle Walker.Math/Octonion - Octonions, from Hubert Holin.Math/Quaternion - Quaternions, from Hubert Holin.Math/Special Functions - Mathematical special functions such as atanh, sinc, and sinhc, from Hubert Holin.Multi Array - Multidimensional containers and adaptors for arrays of contiguous data, from Ron Garcia.Operators - Templates ease arithmetic classes and iterators, from Dave Abrahams and Jeremy Siek.Random - A complete system for random number generation, from Jens Maurer.Rational - A rational number class, from Paul Moore.uBLAS - Basic linear algebra for dense, packed and sparse matrices, from Joerg Walter and Mathias Koch.
Correctness and testing
Concept Check - Tools for generic programming, from Jeremy Siek.Static Assert - Static assertions (compile time assertions), from John Maddock.Test - Support for simple program testing, full unit testing, and for program execution monitoring, from Gennadiy Rozental.
Data structures
Any -
Safe, generic container for single values of different value types
, from Kevlin Henney.Compressed Pair - Empty member optimization, from John Maddock and Howard Hinnant.Optional - Discriminated-union wrapper for optional values, from Fernando Cacciola.Program_options -
Facilities to obtain configuration data from command line, config files
and other sources, from Vladimir Prus.Tuple - Ease definition of functions returning multiple values, and more, from Jaakko Järvi.Variant - Safe, generic, stack-based discriminated union container, from Eric Friedman and Itay Maman.
Input/Output
Format - Type-safe 'printf-like' format operations, from Samuel Krempp.I/O State Savers - Save I/O state to prevent jumbled data, from Daryle Walker.Serialization - Serialization of C++ objects for persistence and marshalling, from Robert Ramey.
Inter-language support
Python - Reflects C++ classes and functions into Python, from Dave Abrahams.
Memory
Pool - Memory pool management, from Steve Cleary.Smart Pointer - Five smart pointer class templates, from Greg Colvin, Beman Dawes, Peter Dimov, and Darin Adler.Utility - Class noncopyable plus checked_delete, checked_array_delete, next, prior function templates, plus base-from-member idiom, from Dave Abrahams and others .
Parsing
Spirit - LL parser framework represents parsers directly as EBNF grammars in inlined C++, from Joel de Guzman and team .
Miscellaneous
CRC - Cyclic Redundancy Code, from Daryle Walker.Compressed Pair - Empty member optimization, from John Maddock and Howard Hinnant.Conversion - Numeric, polymorphic, and lexical casts, from Dave Abrahams and Kevlin Henney.Date Time - A set of facilities to ease programming with dates and times.
, from Jeff Garland.Filesystem - Portable paths, iteration over directories, and other useful filesystem operations, from Beman Dawes.Optional - Discriminated-union wrapper for optional values, from Fernando Cacciola.Timer - Event timer, progress timer, and progress display classes, from Beman Dawes.Tribool - Three-state boolean type, from Douglas Gregor.Utility - Class noncopyable plus checked_delete, checked_array_delete, next, prior function templates, plus base-from-member idiom, from Dave Abrahams and others .
Broken compiler workarounds
Compatibility - Help for non-conforming standard libraries, from Ralf Grosse-Kunstleve and Jens Maurer.Config - Helps boost library developers adapt to compiler idiosyncrasies; not intended for library users, from John Maddock, Beman Dawes, and Vesa Karvonen.KevlinHenney2001Kevlin HenneyBoost.AnyIntroductionThere are times when a generic (in the sense of
general as opposed to
template-based programming) type is needed:
variables that are truly variable, accommodating values of many
other more specific types rather than C++'s normal strict and
static types. We can distinguish three basic kinds of generic
type:Converting types that can hold one of a number of
possible value types, e.g. int and
string, and freely convert between them, for
instance interpreting 5 as "5" or
vice-versa. Such types are common in scripting and other
interpreted
languages.
boost::lexical_cast
supports such conversion functionality.
Discriminated types that contain values of different types but
do not attempt conversion between them, i.e. 5 is
held strictly as an int and is not implicitly
convertible either to "5" or to
5.0. Their indifference to interpretation but
awareness of type effectively makes them safe, generic
containers of single values, with no scope for surprises from
ambiguous conversions.
Indiscriminate types that can refer to anything but are
oblivious to the actual underlying type, entrusting all forms
of access and interpretation to the programmer. This niche is
dominated by void *, which offers plenty of scope
for surprising, undefined behavior.The boost::any class
(based on the class of the same name described in "Valued
Conversions" by Kevlin Henney, C++
Report 12(7), July/August 2000) is a variant value type
based on the second category. It supports copying of any value
type and safe checked extraction of that value strictly against
its type. A similar design, offering more appropriate operators,
can be used for a generalized function adaptor,
any_function, a generalized iterator adaptor,
any_iterator, and other object types that need
uniform runtime treatment but support only compile-time template
parameter conformance.ExamplesThe following code demonstrates the syntax for using
implicit conversions to and copying of any objects:
#include <list>
#include <boost/any.hpp>
using boost::any_cast;
typedef std::list<boost::any> many;
void append_int(many & values, int value)
{
boost::any to_append = value;
values.push_back(to_append);
}
void append_string(many & values, const std::string & value)
{
values.push_back(value);
}
void append_char_ptr(many & values, const char * value)
{
values.push_back(value);
}
void append_any(many & values, const boost::any & value)
{
values.push_back(value);
}
void append_nothing(many & values)
{
values.push_back(boost::any());
}
The following predicates follow on from the previous
definitions and demonstrate the use of queries on any
objects:
bool is_empty(const boost::any & operand)
{
return operand.empty();
}
bool is_int(const boost::any & operand)
{
return operand.type() == typeid(int);
}
bool is_char_ptr(const boost::any & operand)
{
try
{
any_cast<const char *>(operand);
return true;
}
catch(const boost::bad_any_cast &)
{
return false;
}
}
bool is_string(const boost::any & operand)
{
return any_cast<std::string>(&operand);
}
void count_all(many & values, std::ostream & out)
{
out << "#empty == "
<< std::count_if(values.begin(), values.end(), is_empty) << std::endl;
out << "#int == "
<< std::count_if(values.begin(), values.end(), is_int) << std::endl;
out << "#const char * == "
<< std::count_if(values.begin(), values.end(), is_char_ptr) << std::endl;
out << "#string == "
<< std::count_if(values.begin(), values.end(), is_string) << std::endl;
}
The following type, patterned after the OMG's Property Service, defines name-value pairs for arbitrary value types:
struct property
{
property();
property(const std::string &, const boost::any &);
std::string name;
boost::any value;
};
typedef std::list<property> properties;
The following base class demonstrates one approach to
runtime polymorphism based callbacks that also require arbitrary
argument types. The absence of virtual member templates requires
that different solutions have different trade-offs in terms of
efficiency, safety, and generality. Using a checked variant type
offers one approach:
class consumer
{
public:
virtual void notify(const any &) = 0;
...
};
Reference<emphasis>ValueType</emphasis> requirementsValues are strongly informational objects for which
identity is not significant, i.e. the focus is principally on
their state content and any behavior organized around
that. Another distinguishing feature of values is their
granularity: normally fine-grained objects representing simple
concepts in the system such as quantities.As the emphasis of a value lies in its state not its
identity, values can be copied and typically assigned one to
another, requiring the explicit or implicit definition of a
public copy constructor and public assignment operator. Values
typically live within other scopes, i.e. within objects or
blocks, rather than on the heap. Values are therefore normally
passed around and manipulated directly as variables or through
references, but not as pointers that emphasize identity and
indirection.The specific requirements on value types to be used in an
any
are:A ValueType is
CopyConstructible [20.1.3].A ValueType is
optionally Assignable [23.1]. The strong
exception-safety guarantee is required for all forms of
assignment.The destructor for a
ValueType upholds the no-throw
exception-safety guarantee.Header <<ulink url="../../boost/any.hpp">boost/any.hpp</ulink>>namespace boost {
class bad_any_cast;
class any;
template<typename ValueType> ValueType any_cast(const any &);
template<typename ValueType> const ValueType * any_cast(const any *);
template<typename ValueType> ValueType * any_cast(any *);
}Class bad_any_cast3boost::bad_any_castThe exception thrown in the event of a failed
any_cast of an
any value.class bad_any_cast : public std::bad_cast {
public:
virtualconstchar * what() const;
};Descriptionvirtualconstchar *what() const;Class any3boost::anyA class whose instances can hold instances of any
type that satisfies ValueType
requirements.class any {
public:
// construct/copy/destruct
any();
any(const any &);
template<typename ValueType> any(const ValueType &);
any &operator=(const any &);
template<typename ValueType> any &operator=(const ValueType &);
~any();
// modifiersany & swap(any &);
// queriesbool empty() const;
const std::type_info & type() const;
};Description<anchor id="boost.anyconstruct-copy-destruct"/><computeroutput>any</computeroutput> construct/copy/destructany();Postconditionsthis->empty()any(const any & other);Effects Copy constructor that copies content of
other into new instance, so that any content
is equivalent in both type and value to the content of
other, or empty if other is
empty. ThrowsMay fail with a
std::bad_alloc
exception or any exceptions arising from the copy
constructor of the contained type.template<typename ValueType> any(const ValueType & value);EffectsMakes a copy of value, so
that the initial content of the new instance is equivalent
in both type and value to
value.Throwsstd::bad_alloc
or any exceptions arising from the copy constructor of the
contained type.any &operator=(const any & rhs);EffectsCopies content of rhs into
current instance, discarding previous content, so that the
new content is equivalent in both type and value to the
content of rhs, or empty if
rhs.empty().Throwsstd::bad_alloc
or any exceptions arising from the copy constructor of the
contained type. Assignment satisfies the strong guarantee
of exception safety.template<typename ValueType> any &operator=(const ValueType & rhs);EffectsMakes a copy of rhs,
discarding previous content, so that the new content of is
equivalent in both type and value to
rhs.Throwsstd::bad_alloc
or any exceptions arising from the copy constructor of the
contained type. Assignment satisfies the strong guarantee
of exception safety.~any();EffectsReleases any and all resources used in
management of instance.ThrowsNothing.<anchor id="id141128-bb"/><computeroutput>any</computeroutput> modifiersany &swap(any & rhs);EffectsExchange of the contents of
*this and
rhs.Returns*thisThrowsNothing.<anchor id="id141177-bb"/><computeroutput>any</computeroutput> queriesboolempty() const;Returnstrue if instance is
empty, otherwise false.ThrowsWill not throw.const std::type_info &type() const;Returnsthe typeid of the
contained value if instance is non-empty, otherwise
typeid(void).NotesUseful for querying against types known
either at compile time or only at
runtime.Function any_cast3boost::any_castCustom keyword cast for extracting a value
of a given type from an
any.template<typename ValueType> ValueType any_cast(const any & operand);
template<typename ValueType> const ValueType * any_cast(const any * operand);
template<typename ValueType> ValueType * any_cast(any * operand);DescriptionReturns If passed a pointer, it returns a
similarly qualified pointer to the value content if
successful, otherwise null is returned. If passed a value or
reference, it returns a copy of the value content if
successful.ThrowsOverloads taking an
any pointer do not
throw; the overload taking an
any value or reference
throws bad_any_cast if
unsuccessful.RationaleThe value/reference version returns a
copy because the C++ keyword casts return
copies.AcknowledgementsDoug Gregor ported the documentation to the BoostBook format.NicolaiJosuttis2001200220032004Nicolai M. JosuttisPermission to copy, use, modify, sell and distribute this
software is granted provided this copyright notice appears in
all copies. This software is provided "as is" without express or
implied warranty, and with no claim as to its suitability for
any purpose.Boost.ArrayIntroductionThe C++ Standard Template Library STL as part of the C++
Standard Library provides a framework for processing algorithms on
different kind of containers. However, ordinary arrays don't
provide the interface of STL containers (although, they provide
the iterator interface of STL containers).As replacement for ordinary arrays, the STL provides class
std::vector. However,
std::vector<> provides
the semantics of dynamic arrays. Thus, it manages data to be able
to change the number of elements. This results in some overhead in
case only arrays with static size are needed.In his book, Generic Programming and the
STL, Matthew H. Austern introduces a useful wrapper
class for ordinary arrays with static size, called
block. It is safer and has no worse performance than
ordinary arrays. In The C++ Programming
Language, 3rd edition, Bjarne Stroustrup introduces a
similar class, called c_array, which I (Nicolai Josuttis) present
slightly modified in my book The C++ Standard Library -
A Tutorial and Reference, called
carray. This is the essence of these approaches
spiced with many feedback from boost.After considering different names, we decided to name this
class simply array.Note that this class is suggested to be part of the next
Technical Report, which will extend the C++ Standard (see
http://std.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1548.htm).Class array fulfills most
but not all of the requirements of "reversible containers" (see
Section 23.1, [lib.container.requirements] of the C++
Standard). The reasons array is not an reversible STL container is
because:
No constructors are provided.Elements may have an undetermined initial value (see ).swap() has no constant complexity.size() is always constant, based on the second template argument of the type.The container provides no allocator support.It doesn't fulfill the requirements of a "sequence" (see Section 23.1.1, [lib.sequence.reqmts] of the C++ Standard), except that:
front() and back() are provided.operator[] and at() are provided.ReferenceHeader <<ulink url="../../boost/array.hpp">boost/array.hpp</ulink>>namespace boost {
template<typename T, std::size_t N> class array;
template<typename T, std::size_t N> void swap(array<T, N>&, array<T, N>&);
template<typename T, std::size_t N>
booloperator==(const array<T, N>&, const array<T, N>&);
template<typename T, std::size_t N>
booloperator!=(const array<T, N>&, const array<T, N>&);
template<typename T, std::size_t N>
booloperator<(const array<T, N>&, const array<T, N>&);
template<typename T, std::size_t N>
booloperator>(const array<T, N>&, const array<T, N>&);
template<typename T, std::size_t N>
booloperator<=(const array<T, N>&, const array<T, N>&);
template<typename T, std::size_t N>
booloperator>=(const array<T, N>&, const array<T, N>&);
}Class template array3boost::arraySTL compliant container wrapper for arrays of constant sizetemplate<typename T, std::size_t N>
class array {
public:
// typestypedef T value_type;
typedef T* iterator;
typedefconst T* const_iterator;
typedef std::reverse_iterator<iterator> reverse_iterator;
typedef std::reverse_iterator<const_iterator> const_reverse_iterator;
typedef T& reference;
typedefconst T& const_reference;
typedef std::size_t size_type;
typedef std::ptrdiff_t difference_type;
// static constantsstaticconst size_type static_size = N;
// construct/copy/destructtemplate<typename U> array& operator=(const array<U, N>&);
// iterator supportiterator begin();
const_iterator begin() const;
iterator end();
const_iterator end() const;
// reverse iterator supportreverse_iterator rbegin();
const_reverse_iterator rbegin() const;
reverse_iterator rend();
const_reverse_iterator rend() const;
// capacitysize_type size();
bool empty();
size_type max_size();
// element accessreferenceoperator[](size_type);
const_referenceoperator[](size_type) const;
reference at(size_type);
const_reference at(size_type) const;
reference front();
const_reference front() const;
reference back();
const_reference back() const;
const T* data() const;
T* c_array();
// modifiersvoid swap(array<T, N>&);
void assign(const T&);
T elems[N];
};
// specialized algorithmstemplate<typename T, std::size_t N> void swap(array<T, N>&, array<T, N>&);
// comparisonstemplate<typename T, std::size_t N>
booloperator==(const array<T, N>&, const array<T, N>&);
template<typename T, std::size_t N>
booloperator!=(const array<T, N>&, const array<T, N>&);
template<typename T, std::size_t N>
booloperator<(const array<T, N>&, const array<T, N>&);
template<typename T, std::size_t N>
booloperator>(const array<T, N>&, const array<T, N>&);
template<typename T, std::size_t N>
booloperator<=(const array<T, N>&, const array<T, N>&);
template<typename T, std::size_t N>
booloperator>=(const array<T, N>&, const array<T, N>&);Description<anchor id="boost.arrayconstruct-copy-destruct"/><computeroutput>array</computeroutput> construct/copy/destructtemplate<typename U> array& operator=(const array<U, N>& other);Effectsstd::copy(rhs.begin(),rhs.end(), begin())<anchor id="id229808-bb"/><computeroutput>array</computeroutput> iterator supportiteratorbegin();
const_iteratorbegin() const;Returnsiterator for the first elementThrowswill not throwiteratorend();
const_iteratorend() const;Returnsiterator for position after the last elementThrowswill not throw<anchor id="id229873-bb"/><computeroutput>array</computeroutput> reverse iterator supportreverse_iteratorrbegin();
const_reverse_iteratorrbegin() const;Returnsreverse iterator for the first element of reverse iterationreverse_iteratorrend();
const_reverse_iteratorrend() const;Returnsreverse iterator for position after the last element in reverse iteration<anchor id="id229930-bb"/><computeroutput>array</computeroutput> capacitysize_typesize();ReturnsNboolempty();ReturnsN==0Throwswill not throwsize_typemax_size();ReturnsNThrowswill not throw<anchor id="id227251-bb"/><computeroutput>array</computeroutput> element accessreferenceoperator[](size_type i);
const_referenceoperator[](size_type i) const;Requiresi < NReturnselement with index iThrowswill not throw.referenceat(size_type i);
const_referenceat(size_type i) const;Returnselement with index iThrowsstd::range_error if i >= Nreferencefront();
const_referencefront() const;RequiresN > 0Returnsthe first elementThrowswill not throwreferenceback();
const_referenceback() const;RequiresN > 0Returnsthe last elementThrowswill not throwconst T*data() const;ReturnselemsThrowswill not throwT*c_array();ReturnselemsThrowswill not throw<anchor id="id227478-bb"/><computeroutput>array</computeroutput> modifiersvoidswap(array<T, N>& other);Effectsstd::swap_ranges(begin(), end(), other.begin())Complexitylinear in Nvoidassign(const T& value);Effectsstd::fill_n(begin(), N, value)<anchor id="id227563-bb"/><computeroutput>array</computeroutput> specialized algorithmstemplate<typename T, std::size_t N> voidswap(array<T, N>& x, array<T, N>& y);Effectsx.swap(y)Throwswill not throw.<anchor id="id287136-bb"/><computeroutput>array</computeroutput> comparisonstemplate<typename T, std::size_t N>
booloperator==(const array<T, N>& x, const array<T, N>& y);Returnsstd::equal(x.begin(), x.end(), y.begin())template<typename T, std::size_t N>
booloperator!=(const array<T, N>& x, const array<T, N>& y);Returns!(x == y)template<typename T, std::size_t N>
booloperator<(const array<T, N>& x, const array<T, N>& y);Returnsstd::lexicographical_compare(x.begin(), x.end(), y.begin(), y.end())template<typename T, std::size_t N>
booloperator>(const array<T, N>& x, const array<T, N>& y);Returnsy < xtemplate<typename T, std::size_t N>
booloperator<=(const array<T, N>& x, const array<T, N>& y);Returns!(y < x)template<typename T, std::size_t N>
booloperator>=(const array<T, N>& x, const array<T, N>& y);Returns!(x < y)Design RationaleThere was an important design tradeoff regarding the
constructors: We could implement array as an "aggregate" (see
Section 8.5.1, [dcl.init.aggr], of the C++ Standard). This would
mean:
An array can be initialized with a
brace-enclosing, comma-separated list of initializers for the
elements of the container, written in increasing subscript
order:boost::array<int,4> a = { { 1, 2, 3 } };Note that if there are fewer elements in the
initializer list, then each remaining element gets
default-initialized (thus, it has a defined value).However, this approach has its drawbacks: passing no initializer list means that the elements
have an indetermined initial value, because the rule says
that aggregates may have:
No user-declared constructors.No private or protected non-static data members.No base classes.No virtual functions.Nevertheless, The current implementation uses this approach.Note that for standard conforming compilers it is possible to
use fewer braces (according to 8.5.1 (11) of the Standard). That is,
you can initialize an array as follows:boost::array<int,4> a = { 1, 2, 3 };
I'd appreciate any constructive feedback. Please note: I don't have time to read all boost
mails. Thus, to make sure that feedback arrives to me, please send
me a copy of each mail regarding this class.The code is provided "as is" without expressed or implied
warranty.For more information...To find more details about using ordinary arrays in C++ and
the framework of the STL, see e.g.
The C++ Standard Library - A Tutorial and Reference
by Nicolai M. Josuttis
Addison Wesley Longman, 1999
ISBN 0-201-37926-0Home Page of Nicolai
JosuttisAcknowledgementsDoug Gregor ported the documentation to the BoostBook format.ConceptsAssignableInputIteratorOutputIteratorForwardIteratorBidirectionalIteratorRandomAccessIteratorDefaultConstructibleCopyConstructibleEqualityComparableLessThanComparableSignedInteger20012002Indiana University20002001University of Notre Dame du Lac2000Jeremy SiekLie-Quan LeeAndrew Lumsdaine1996199719981999Silicon Graphics Computer Systems, Inc.1994Hewlett-Packard CompanyThis product includes software developed at the University
of Notre Dame and the Pervasive Technology Labs at Indiana
University. For technical information contact Andrew Lumsdaine
at the Pervasive Technology Labs at Indiana University. For
administrative and license questions contact the Advanced
Research and Technology Institute at 351 West 10th Street.
Indianapolis, Indiana 46202, phone 317-278-4100, fax
317-274-5902.Some concepts based on versions from the MTL draft manual
and Boost Graph and Property Map documentation, the SGI Standard
Template Library documentation and the Hewlett-Packard STL,
under the following license:
Permission to use, copy, modify, distribute and
sell this software and its documentation for any purpose is
hereby granted without fee, provided that the above copyright
notice appears in all copies and that both that copyright
notice and this permission notice appear in supporting
documentation. Silicon Graphics makes no representations
about the suitability of this software for any purpose. It is
provided "as is" without express or implied
warranty.
Concept referenceConcept Assignable7AssignableDescriptionAssignable types must have copy constructors,
operator= for assignment, and the swap()
function defined.Refinement ofCopyConstructibleNotationXA type playing the role of assignable-type in the Assignable concept.xyObjects of type XValid expressionsNameExpressionTypeSemanticsAssignmentx = yX &Require operator=Swapswap(x, y)voidRequire swap() functionModelsintSee alsoCopyConstructibleConcept InputIterator7InputIteratorDescriptionAn input iterator is an iterator that can read through a sequence of
values. It is single-pass (old values of the iterator cannot be
re-used), and read-only.An input iterator represents a position in a sequence. Therefore, the
iterator can point into the sequence (returning a value when dereferenced
and being incrementable), or be off-the-end (and not dereferenceable or
incrementable).Refinement ofAssignableDefaultConstructibleEqualityComparableAssociated typesvalue_typestd::iterator_traits<Iter>::value_typeThe value type of the iterator (not necessarily what
*i returns)difference_typestd::iterator_traits<Iter>::difference_typeThe difference type of the iteratorcategorystd::iterator_traits<Iter>::iterator_categoryThe category of the iteratorNotationIterA type playing the role of iterator-type in the InputIterator concept.ijObjects of type IterxObject of type value_typeType expressionsCategory tagcategory must be
derived from std::input_iterator_tag, a model of DefaultConstructible, and a model of CopyConstructible.
Value type copy constructibilityvalue_type must be
a model of CopyConstructible.
Difference type propertiesdifference_type must be
a model of SignedInteger.
Valid expressionsNameExpressionTypePreconditionSemanticsPostconditionDereference*iConvertible to value_typei is incrementable (not
off-the-end)Preincrement++iIter &i is incrementable (not
off-the-end)Postincrementi++i is incrementable (not
off-the-end)Equivalent to (void)(++i)i is dereferenceable or
off-the-endPostincrement and dereference*i++Convertible to value_typei is incrementable (not
off-the-end)Equivalent to {value_type t = *i; ++i; return t;}i is dereferenceable or
off-the-endComplexity
All iterator operations must take amortized constant time.
Modelsstd::istream_iteratorSee alsoDefaultConstructibleEqualityComparableForwardIteratorOutputIteratorConcept OutputIterator7OutputIteratorDescriptionAn output iterator is an iterator that can write a sequence of
values. It is single-pass (old values of the iterator cannot be
re-used), and write-only.An output iterator represents a position in a (possibly infinite)
sequence. Therefore, the iterator can point into the sequence (returning
a value when dereferenced and being incrementable), or be off-the-end
(and not dereferenceable or incrementable).Associated typesvalue_typestd::iterator_traits<Iter>::value_typeThe stated value type of the iterator (should be
void for an output iterator that does not model some other
iterator concept).difference_typestd::iterator_traits<Iter>::difference_typeThe difference type of the iteratorcategorystd::iterator_traits<Iter>::iterator_categoryThe category of the iteratorNotationIterA type playing the role of iterator-type in the OutputIterator concept.ValueTypeA type playing the role of value-type in the OutputIterator concept.ijObjects of type IterxObject of type ValueTypeType expressionsThe type Iter must be a model of Assignable.The type ValueType must be a model of Assignable.The type Iter must be a model of DefaultConstructible.The type Iter must be a model of
EqualityComparable.Category tagcategory must be
derived from std::output_iterator_tag, a model of DefaultConstructible, and a model of CopyConstructible.
Difference type propertiesdifference_type must be
a model of SignedInteger.
Valid expressionsNameExpressionTypePreconditionSemanticsPostconditionDereference*ii is incrementable (not
off-the-end)Dereference and assign*i = xi is incrementable (not
off-the-end)*i may not be written to again until it has
been incremented.Preincrement++iIter &i is incrementable (not
off-the-end)Postincrementi++i is incrementable (not
off-the-end)Equivalent to (void)(++i)i is dereferenceable or
off-the-endPostincrement, dereference, and assign*i++ = xi is incrementable (not
off-the-end)Equivalent to {*i = t; ++i;}i is dereferenceable or
off-the-endComplexity
All iterator operations must take amortized constant time.
Modelsstd::ostream_iterator...std::insert_iterator...std::front_insert_iterator...std::back_insert_iterator...See alsoConcept ForwardIterator7ForwardIteratorDescriptionA forward iterator is an iterator that can read through a sequence of
values. It is multi-pass (old values of the iterator can be
re-used), and can be either mutable (data pointed to by it can be
changed) or not mutable.An iterator represents a position in a sequence. Therefore, the
iterator can point into the sequence (returning a value when dereferenced
and being incrementable), or be off-the-end (and not dereferenceable or
incrementable).Refinement ofInputIteratorOutputIteratorAssociated typesvalue_typestd::iterator_traits<Iter>::value_typeThe value type of the iteratorcategorystd::iterator_traits<Iter>::iterator_categoryThe category of the iteratorNotationIterA type playing the role of iterator-type in the ForwardIterator concept.ijObjects of type IterxObject of type value_typeType expressionsCategory tagcategory must be
derived from std::forward_iterator_tag.
Valid expressionsNameExpressionTypePreconditionSemanticsPostconditionDereference*iconst-if-not-mutable value_type &i is incrementable (not
off-the-end)Member accessi->{member-name} (return type is pointer-to-object type)const-if-not-mutable value_type *i is incrementable (not
off-the-end)Preincrement++iIter &i is incrementable (not
off-the-end)Postincrementi++Iteri is incrementable (not
off-the-end)Equivalent to {Iter j = i; ++i; return j;}i is dereferenceable or
off-the-endComplexity
All iterator operations must take amortized constant time.
InvariantsPredecrement must return object&i = &(++i)Unique path through sequencei == j implies ++i == ++jModelsT *std::hash_set<T>::iteratorSee alsoBidirectionalIteratorConcept BidirectionalIterator7BidirectionalIteratorDescriptionA bidirectional iterator is an iterator that can read through a sequence
of values. It can move in either direction through the sequence, and can
be either mutable (data pointed to by it can be changed) or not mutable.An iterator represents a position in a sequence. Therefore, the
iterator can point into the sequence (returning a value when dereferenced
and being incrementable), or be off-the-end (and not dereferenceable or
incrementable).Refinement ofForwardIteratorAssociated typesvalue_typestd::iterator_traits<Iter>::value_typeThe value type of the iteratorcategorystd::iterator_traits<Iter>::iterator_categoryThe category of the iteratorNotationIterA type playing the role of iterator-type in the BidirectionalIterator concept.ijObjects of type IterxObject of type value_typeType expressionsCategory tagcategory must be
derived from std::bidirectional_iterator_tag.
Valid expressionsNameExpressionTypePreconditionSemanticsPostconditionPredecrement--iIter &i is incrementable (not
off-the-end) and some dereferenceable iterator j exists
such that i == ++jPostdecrementi--IterSame as for predecrementEquivalent to {Iter j = i; --i; return j;}i is dereferenceable or
off-the-endComplexity
All iterator operations must take amortized constant time.
InvariantsPredecrement must return object&i = &(--i)Unique path through sequencei == j implies --i == --jIncrement and decrement are inverses++i; --i; and --i; ++i; must end up with the
value of i unmodified, if i both of the
operations in the pair are valid.
ModelsT *std::list<T>::iteratorSee alsoRandomAccessIteratorConcept RandomAccessIterator7RandomAccessIteratorDescriptionA random access iterator is an iterator that can read through
a sequence of values. It can move in either direction through the
sequence (by any amount in constant time), and can be either mutable
(data pointed to by it can be changed) or not mutable.An iterator represents a position in a sequence. Therefore,
the iterator can point into the sequence (returning a value when
dereferenced and being incrementable), or be off-the-end (and not
dereferenceable or incrementable).Refinement ofBidirectionalIteratorLessThanComparableAssociated typesvalue_typestd::iterator_traits<Iter>::value_typeThe value type of the iteratorcategorystd::iterator_traits<Iter>::iterator_categoryThe category of the iteratordifference_typestd::iterator_traits<Iter>::difference_typeThe difference type of the iterator (measure of the number
of steps between two iterators)NotationIterA type playing the role of iterator-type in the RandomAccessIterator concept.ijObjects of type IterxObject of type value_typenObject of type difference_typeint_offObject of type intType expressionsCategory tagcategory must be
derived from std::random_access_iterator_tag.
Valid expressionsNameExpressionTypeSemanticsMotioni += nIter &Equivalent to applying i++n times
if n is positive, applying i---n times if n is negative, and to a null
operation if n is zero.Motion (with integer offset)i += int_offIter &Equivalent to applying i++n times
if n is positive, applying i---n times if n is negative, and to a null
operation if n is zero.Subtractive motioni -= nIter &Equivalent to i+=(-n)Subtractive motion (with integer offset)i -= int_offIter &Equivalent to i+=(-n)Additioni + nIterEquivalent to {Iter j = i; j += n; return j;}Addition with integeri + int_offIterEquivalent to {Iter j = i; j += n; return j;}Addition (count first)n + iIterEquivalent to i + nAddition with integer (count first)int_off + iIterEquivalent to i + nSubtractioni - nIterEquivalent to i + (-n)Subtraction with integeri - int_offIterEquivalent to i + (-n)Distancei - jdifference_typeThe number of times i must be incremented (or
decremented if the result is negative) to reach j. Not
defined if j is not reachable from
i.Element accessi[n]const-if-not-mutable value_type &Equivalent to *(i + n)Element access with integer indexi[int_off]const-if-not-mutable value_type &Equivalent to *(i + n)Complexity
All iterator operations must take amortized constant time.
ModelsT *std::vector<T>::iteratorstd::vector<T>::const_iteratorstd::deque<T>::iteratorstd::deque<T>::const_iteratorSee alsoLessThanComparableConcept DefaultConstructible7DefaultConstructibleDescriptionDefaultConstructible objects only need to have a default
constructor.NotationXA type playing the role of default-constructible-type in the DefaultConstructible concept.Valid expressionsNameExpressionTypeSemanticsConstructionX()XConstruct an instance of the type with default parameters.Modelsintstd::vector<double>Concept CopyConstructible7CopyConstructibleDescriptionCopy constructible types must be able to be constructed from another
member of the type.NotationXA type playing the role of copy-constructible-type in the CopyConstructible concept.xyObjects of type XValid expressionsNameExpressionTypeSemanticsCopy constructionX(x)XRequire copy constructor.ModelsintConcept EqualityComparable7EqualityComparableDescriptionEquality Comparable types must have == and
!= operators.NotationXA type playing the role of comparable-type in the EqualityComparable concept.xyObjects of type XValid expressionsNameExpressionTypeEquality testx == yConvertible to boolInequality testx != yConvertible to boolModelsintstd::vector<int>Concept LessThanComparable7LessThanComparableDescriptionLessThanComparable types must have <,
>, <=, and >=
operators.NotationXA type playing the role of comparable-type in the LessThanComparable concept.xyObjects of type XValid expressionsNameExpressionTypeSemanticsLess thanx < yConvertible to boolDetermine if one value is less than another.Less than or equalx <= yConvertible to boolDetermine if one value is less than or equal to another.Greater thanx > yConvertible to boolDetermine if one value is greater than another.Greater than or equal tox >= yConvertible to boolDetermine if one value is greater than or equal to another.ModelsintConcept SignedInteger7SignedIntegerRefinement ofCopyConstructibleAssignableDefaultConstructibleEqualityComparableLessThanComparableNotationTA type playing the role of integral-type in the SignedInteger concept.xyzObjects of type TabObjects of type intType expressionsConversion to intT must be
convertible to int.
Valid expressionsNameExpressionTypeConversion from intT(a)TPreincrement++xT &Predecrement--xT &Postincrementx++TPostdecrementx--TSumx + yTSum with intx + aTSum-assignmentx += yT &Sum-assignment with intx += aT &Differencex - yTDifference with intx - aTProductx * yTProduct with intx * aTProduct-assignment with intx *= aT &Product with int on lefta * xTQuotientx / yTQuotient with intx / aTRight-shiftx >> yTRight-shift with intx >> aTRight-shift-assignment with intx >>= aT &Less-than comparisonx < yConvertible to boolLess-than comparison with intx < aConvertible to boolLess-than comparison with size_tx < boost::sample_value < std::size_t >()Convertible to boolGreater-than comparisonx > yConvertible to boolGreater-than comparison with intx > aConvertible to boolLess-than-or-equal comparisonx <= yConvertible to boolLess-than-or-equal comparison with intx <= aConvertible to boolGreater-than-or-equal comparisonx >= yConvertible to boolGreater-than-or-equal comparison with intx >= aConvertible to boolGreater-than-or-equal comparison with int on lefta >= xConvertible to boolEquality comparisonx == yConvertible to boolEquality comparison with intx == aConvertible to boolSee alsoJeffGarland2001200220032004CrystalClear Software, IncSubject 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)Boost.Date_TimeIntroduction
A set of date-time libraries based on generic programming concepts.
ConceptualMotivation
The motivation for this library comes from working with and helping build several date-time libraries on several projects. Date-time libraries provide fundamental infrastructure for most development projects. However, most of them have limitations in their ability to calculate, format, convert, or perform some other functionality. For example, most libraries do not correctly handle leap seconds, provide concepts such as infinity, or provide the ability to use high resolution or network time sources. These libraries also tend to be rigid in their representation of dates and times. Thus customized policies for a project or subproject are not possible.
Programming with dates and times should be almost as simple and natural as programming with strings and integers. Applications with lots of temporal logic can be radically simplified by having a robust set of operators and calculation capabilities. Classes should provide the ability to compare dates and times, add lengths or time durations, retrieve dates and times from clocks, and work naturally with date and time intervals.
Another motivation for development of the library was to apply modern C++ library design techniques to the date-time domain. Really to build a framework for the construction of building temporal types. For example, by providing iterators and traits classes to control fundamental properties of the library. To the authors knowledge this library is the only substantial attempt to apply modern C++ to a date-time library.
Domain Concepts
The date time domain is rich in terminology and problems.
The following is a brief introduction to the concepts you
will find reflected in the library.
The library supports 3 basic temporal types:
Time Point -- Specifier
for a location in the time continuum.
Time Duration -- A
length of time unattached to any point on the time continuum.
Time Interval -- A duration
of time attached to a specific point in the time continuum.
Also known as a time period.
Each of these temporal types has a Resolution which is defined by the smallest representable duration. A Time system provides all these categories of temporal types as well as the rules for labeling and calculating with time points. Calendar Systems are simply time systems with a maximum resolution of one day. The Gregorian system is the most widely used calendar system today (the ISO system is basically a derivative of this). However, there are many other calendar systems as well. UTC (Coordinated Universal Time) is a widely used civil time system. UTC is adjusted for earth rotation at longitude 0 by the use of leap seconds (This is not predictable, only as necessary). Most local time systems are based on UTC but are also adjusted for earth rotation so that daylight hours are similar everywhere. In addition, some local times include daylight savings time (DST) adjustments to shift the daylight hours during the summer.
A Clock Device is software component (tied to some hardware) that provides the current date or time with respect to a time system. A clock can measure the current time to a known resolution which may be higher or lower than a particular time representation.
The library provides support for calculating with dates and times. However, time calculations are not quite the same as calculating with integers. If you are serious about the accuracy of your time calculations need to read about Stability, Predictability, and Approximations.
Basic TerminologyCalculationsStability, Predictability, and ApproximationsReferencesDesign Concepts
A large part of the genesis of this library has been the observation that few date-time libraries are built in a fashion that allows customization and extension. A typical example, the calendar logic is built directly into the date class. Or the clock retrieval functions are built directly into the time class. These design decisions usually make it impossible to extend or change the library behavior. At a more fundamental level, there are usually assumptions about the resolution of time representation or the gregorian calendar.
Often times, the result is that a project must settle for a less than complete library because of a requirement for high resolution time representation or other assumptions that do not match the implementation of the library. This is extremely unfortunate because development of a library of this sort is far from a trivial task.
While the design is far from perfect the current design is far more flexible than any date-time library the author is aware of. It is expected that the various aspects of extensibility will be better documented in future versions. Information about the design goals of the library is summarized here.
More Information
The design of the library is currently being evolved using
Wiki and email discussions. You can find more information at:
Boost Wiki GDTL Start PageFull Doxygen Reference ManualGregorianGregorian Date SystemIntroduction --
Usage ExamplesIntroductionThe gregorian date system provides a date programming system based the Gregorian Calendar. The first introduction of the Gregorian calendar was in 1582 to fix an error in the Julian Calendar. However, many local jurisdictions did not adopt this change until much later. Thus there is potential confusion with historical dates.
The implemented calendar is a "propleptic Gregorian calendar" which extends dates back prior to the Gregorian Calendar's first adoption in 1582. The current implementation supports dates in the range 1400-Jan-01 to 10000-Jan-01. Many references will represent dates prior to 1582 using the Julian Calendar, so caution is in order if accurate calculations are required on historic dates. See Calendrical Calculations by Reingold & Dershowitz for more details. Date information from Calendrical Calculations has been used to cross-test the correctness of the Gregorian calendar implementation.
All types for the gregorian system are found in namespace boost::gregorian. The library supports a convenience header boost/date_time/gregorian/gregorian_types.hpp that will include all the classes of the library with no input/output dependency. Another header boost/date_time/gregorian/gregorian.hpp will include the types and the input/output code.
The class boost::gregorian::date is the primary temporal type for users. If you are interested in learning about writing programs do specialized date calculations such as finding the "first sunday in april" see the date generators and algorithms page.
Usage ExamplesExampleDescriptionDays AliveDays Till New YearSimple date arithmetic. Retrieve current day from clock.Dates as stringsSimple parsing and formatting of dates from/to stringsDate Period CalculationsSee if a date is in a set of date periods (eg: is it a holiday/weekend)Print a monthSmall utility program which prints out all the days in a month from command line. Need to know if 1999-Jan-1 was a Friday or a Saturday? This program shows how to do it.Print HolidaysUses date generators to convert abstract specification into concrete set of dates.Date ClassIntroduction --
Header --
Construction --
Construct from String --
Construct from Clock --
Accessors --
Convert to String --
OperatorsIntroduction
The class boost::gregorian::date is the primary interface for date programming. In general, the date class is immutable once constructed although it does allow assignment.
Other techniques for creating dates include date iterators and date algorithms or generators.
Header
#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o
or
#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types
ConstructionSyntaxDescriptionExampledate(greg_year year, greg_month month, greg_day day)Construct from parts of date. Throws bad_year, bad_day_of_month, or bad_day_month (derivatives of std::out_of_range) if the year, month or day are out of range.date d(2002,Jan,10)date(date d)Copy constructordate d1(d)date(special_values sv)Constructor for infinities, not-a-date-time, max_date_time, and min_date_time
date d1(neg_infin);
date d2(pos_infin);
date d3(not_a_date_time);
date d4(max_date_time);
date d5(min_date_time);date;Default constructor. Creates a date object initialized to not_a_date_time. NOTE: this constructor can be disabled by defining DATE_TIME_NO_DEFAULT_CONSTRUCTOR (see compiler_config.hpp)date d; // d => not_a_date_timeConstruct from StringSyntaxDescriptionExampledate from_string(const std::string&)From delimited date string where with order year-month-day eg: 2002-1-25
std::string ds("2002/1/25");
date d(from_string(ds))date from_undelimited_string(const std::string&)From iso type date string where with order year-month-day eg: 20020125
std::string ds("20020125");
date d(from_undelimited_string(ds))Construct from ClockSyntaxDescriptionExampleday_clock::local_day()Get the local day based on the time zone settings of the computer.date d(day_clock::local_day())day_clock::universal_day()Get the UTC day.date d(day_clock::universal_day())AccessorsSyntaxDescriptionExamplegreg_year year() constGet the year part of the date.
date d(2002,Jan,10);
d.year() --> 2002;greg_month month() constGet the month part of the date.
date d(2002,Jan,10);
d.month() --> 1;greg_day day() const Get the day part of the date.
date d(2002,Jan,10);
d.day() --> 10;greg_ymd year_month_day() constReturn a year_month_day struct. More efficient when all 3 parts of the date are needed.
date d(2002,Jan,10);
date::ymd_type ymd = d.year_month_day();
ymd.year --> 2002, ymd.month --> 1, ymd.day --> 10greg_day_of_week day_of_week() constGet the day of the week (eg: Sunday, Monday, etc.
date d(2002,Jan,10);
d.day() --> Thursday;bool is_infinity() constReturns true if date is either positive or negative infinity
date d(pos_infin);
d.is_infinity() --> true;bool is_neg_infinity() constReturns true if date is negative infinity
date d(neg_infin);
d.is_neg_infinity() --> true;bool is_pos_infinity() constReturns true if date is positive infinity
date d(neg_infin);
d.is_pos_infinity() --> true;bool is_not_a_date() constReturns true if value is not a date
date d(not_a_date_time);
d.is_not_a_date() --> true;long modjulian_day() constReturns the modified julian day for the date.long julian_day() constReturns the julian day for the date.int week_number() constReturns the ISO 8601 week number for the date.Convert to StringSyntaxDescriptionExamplestd::string to_simple_string(date d)To YYYY-mmm-DD string where mmm 3 char month name.2002-Jan-01std::string to_iso_string(date d)To YYYYMMDD where all components are integers.20020131std::string to_iso_extended_string(date d) To YYYY-MM-DD where all components are integers.2002-01-31OperatorsSyntaxDescriptionExampleoperator<<Stream output operator
date d(2002,Jan,1)
std::cout << d << std::endl;
operator==, operator!=,
operator>, operator<
operator>=, operator<=A full complement of comparison operatorsd1 == d2, etcdate operator+(date_duration) constReturn a date adding a day offset
date d(2002,Jan,1);
date_duration dd(1);
date d2 = d + dd;
date operator-(date_duration) constReturn a date by adding a day offset
date d(2002,Jan,1);
date_duration dd(1);
date d2 = d - dd;
date_duration operator-(date) constReturn a date duration by subtracting two dates
date d1(2002,Jan,1);
date d2(2002,Jan,2);
date_duration dd = d2-d1;
topDate Duration (aka Days)Introduction --
Header --
Construction --
OperatorsIntroduction
As of version 1_32 the date_duration class has been typdefed as days in the boost::gregorian namespace. Throughout the examples you will find days used instead of date_duration.
The class boost::gregorian::date_duration is a simple day count used for arithmetic with gregorian::date. A duration can be either positive or negative.
Header
#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o
or
#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types
ConstructionSyntaxDescriptionExampledate_duration(long)Create a duration count. date_duration dd(3); //3 daysAccessorsSyntaxDescriptionExamplelong days() const Get the day count.date_duration dd(3); dd.days() --> 3bool is_negative() constTrue if number of days is less than zero.date_duration dd(-1); dd.is_negative() --> truestatic date_duration unit()Return smallest possible unit of duration type.date_duration::unit() --> date_duration(1)OperatorsSyntaxDescriptionExample
operator==, operator!=,
operator>, operator<
operator>=, operator<=
A full complement of comparison operatorsdd1 == dd2, etcdate_duration operator+(date_duration) constAdd date durations.
date_duration dd1(3);
date_duration dd2(5);
date_duration dd3 = dd1 + dd2;
date_duration operator-(date_duration) constSubtract durations.
date_duration dd1(3);
date_duration dd2(5);
date_duration dd3 = dd1 - dd2;
topDate PeriodIntroduction --
Header --
Construction --
Accessors --
Convert to String --
OperatorsIntroduction
The class boost::gregorian::date_period provides direct representation for ranges between two dates. Periods provide the ability to simplify some types of calculations by simplifying the conditional logic of the program. For example, testing if a date is within an irregular schedule such as a weekend or holiday can be accomplished using collections of date periods. This is facilitated by several methods that allow evaluation if a date_period intersects with another date period, and to generate the period resulting from the intersection. The period calculation example provides an example of this.
Date periods used in combination with infinity values have the ability to represent complex concepts such as 'until further notice'.
Header
#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o
or
#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types
ConstructionSyntaxDescriptionExampledate_period(date begin, date end) Create a period as [begin, end). If last is <= begin then the period will be defined as null.date_period dp(date(2002,Jan,10), date(2002,Jan,12));date_period(date start, date_duration len) Create a period as [begin, begin+len). If len is <= zero then the period will be defined as null.date_period dp(date(2002,Jan,10), date_duration(2));date_period(date_period rhs) Copy constructor date_period dp1(dp)AccessorsSyntaxDescriptionExampledate begin() const Return first day of period.
date_period dp(date(2002,Jan,1), date(2002,Jan,10));
dp.begin() --> 2002-Jan-01
date last() constReturn last date in the period
date_period dp(date(2002,Jan,1), date(2002,Jan,10));
dp.last() --> 2002-Jan-09
date end() constReturn one past the last in period
date_period dp(date(2002,Jan,1), date(2002,Jan,10));
dp.end() --> 2002-Jan-10
date_duration length() constReturn the length of the date_period
date_period dp(date(2002,Jan,1), date_duration(2));
dp.length() --> 2
bool is_null() constTrue if period is not well formed. eg: start less than end
date_period dp(date(2002,Jan,10), date(2002,Jan,1));
dp.begin() --> true
bool contains(date) constTrue if date is within the period
date_period dp(date(2002,Jan,1), date(2002,Jan,10));
dp.contains(date(2002,Jan,2)) --> true
bool contains(date_period) constTrue if date period is within the period
date_period dp1(date(2002,Jan,1), date(2002,Jan,10));
date_period dp2(date(2002,Jan,2), date(2002,Jan,3));
dp1.contains(dp2) --> true
dp2.contains(dp1) --> false
bool intersects(date_period) constTrue if periods overlap
date_period dp1(date(2002,Jan,1), date(2002,Jan,10));
date_period dp2(date(2002,Jan,2), date(2002,Jan,3));
dp2.intersects(dp1) --> true
date_period intersection(date_period) constCalculate the intersection of 2 periods. Null if no intersection.
date_period dp1(date(2002,Jan,1), date(2002,Jan,10));
date_period dp2(date(2002,Jan,2), date(2002,Jan,3));
dp2.intersection(dp1) --> dp2
date_period is_adjacent(date_period) constCheck if two periods are adjacent, but not overlapping.
date_period dp1(date(2002,Jan,1), date(2002,Jan,3));
date_period dp2(date(2002,Jan,3), date(2002,Jan,10));
dp2.is_adjacent(dp1) --> true
date_period is_after(date) constDetermine the period is after a given date.
date_period dp1(date(2002,Jan,10), date(2002,Jan,30));
date d(2002,Jan,3);
dp1.is_after(d) --> true
date_period is_before(date) constDetermine the period is before a given date.
date_period dp1(date(2002,Jan,1), date(2002,Jan,3));
date d(2002,Jan,10);
dp1.is_before(d) --> true
date_period merge(date_period) constReturns union of two periods. Null if no intersection.
date_period dp1(date(2002,Jan,1), date(2002,Jan,10));
date_period dp2(date(2002,Jan,9), date(2002,Jan,31));
dp2.merge(dp1) --> 2002-Jan-01/2002-Jan-31
date_period span(date_period) constCombines two periods and any gap between them such that start = min(p1.start, p2.start) and end = max(p1.end , p2.end)
date_period dp1(date(2002,Jan,1), date(2002,Jan,5));
date_period dp2(date(2002,Jan,9), date(2002,Jan,31));
dp2.hull(dp1) --> 2002-Jan-01/2002-Jan-31
date_period shift(date_duration)Add duration to both start and end.
date_period dp1(date(2002,Jan,1), date(2002,Jan,10));
dp1.shift(date_duration(1)); --> 2002-Jan-02/2002-Jan-11
Convert to StringSyntaxDescriptionExamplestd::string to_simple_string(date_period dp)To [YYYY-mmm-DD/YYYY-mmm-DD] string where mmm is 3 char month name.[2002-Jan-01/2002-Jan-31]OperatorsSyntaxDescriptionExampleoperator<<ostream operator for date_period. Uses facet to format time points. Typical output: [2002-Jan-01/2002-Jan-31].std::cout << dp << std::endl;
operator==, operator!=,
operator>, operator<
A full complement of comparison operators dp1 == dp2, etcoperator<True if dp1.end() less than dp2.begin() dp1 < dp2, etcoperator>True if dp1.begin() greater than dp2.end()dp1 > dp2, etctopDate IteratorsIntroduction --
Header --
OverviewIntroduction
Date iterators provide a standard mechanism for iteration through dates. Date iterators are a model of Input Iterator and can be used to populate collections with dates and other date generation tasks. For example, the print month example iterates through all the days in a month and prints them.
All of the iterators here derive from boost::gregorian::date_iterator.
Header
#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o
or
#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types
OverviewClassConstruction ParametersDescriptiondate_iteratorCommon base class for all day level iterators.day_iteratordate start_date, int day_count=1Iterate day_count days at a time.week_iterator date start_date, int week_offset=1Iterate week_offset weeks at a time.month_iteratordate start_date, int month_offset=1
Iterate month_offset months. There are special rules for handling the end of the month. These are: if start date is last day of the month, always adjust to last day of the month. If date is beyond the end of the month (eg: jan 31 + 1 month) adjust back to end of month.
year_iteratordate start_date, int year_offset=1Iterate year_offset years. The year_iterator will always land on the day of the date parameter except when date is Feb 28 in a non-leap year. In this case the iterator will return Feb 29 for leap years (eg: 2003-Feb-28, 2004-Feb-29, 2005-Feb-28).topDate Generators/AlgorithmsDate Generators/AlgorithmsIntroduction --
Header --
Class Overview --
Function OverviewIntroduction
Date algorithms or generators are tools for generating other dates or schedules of dates. A generator function starts with some part of a date such as a month and day and is supplied another part to then generate a concrete date. This allows the programmer to represent concepts such as "The first Sunday in February" and then create a concrete set of dates when provided with one or more years.
Note: As of boost version 1_31_0, date generator names have been changed. Old names are still available but are no longer documented and may someday be deprecated
Also provided are stand-alone functions for generating a date, or calculation a duration of days. These functions take a date object and a weekday object as parameters.
All date generator classes and functions are in the boost::gregorian namespace.
The print holidays example shows a detailed usage example.
Header
#include "boost/date_time/date_generators.hpp"
OverviewClassConstruction Parametersget_date ParameterDescriptionExampleyear_based_generatorabstract base classgreg_year yearA unifying date_generator base type for: partial_date, nth_day_of_the_week_in_month, first_day_of_the_week_in_month, and last_day_of_the_week_in_month
The print holidays example shows a detailed usage example.
last_day_of_the_week_in_monthgreg_weekday or weekday, greg_month or monthgreg_year or yearCalculate something like last Monday of January
last_day_of_the_week_in_month lwdm(Monday,Jan);
date d = lwdm.get_date(2002);//2002-Jan-28
first_day_of_the_week_in_monthgreg_weekday or weekday, greg_month or monthgreg_year or yearCalculate something like first Monday of January
first_day_of_the_week_in_month fdm(Monday,Jan);
date d = fdm.get_date(2002);//2002-Jan-07
partial_dategreg_day, greg_month or monthgreg_yearGenerates a date by applying the year to the given month and day.
partial_date pd(1,Jan);
date d = pd.get_date(2002);//2002-Jan-01
first_day_of_the_week_after greg_weekday or weekdaydateCalculate something like First Sunday after Jan 1,2002
first_day_of_the_week_after fdaf(Monday);
date d = fdaf.get_date(date(2002,Jan,1));//2002-Jan-07
first_day_of_the_week_before greg_weekday or weekdaydateCalculate something like First Monday before Feb 1,2002
first_day_of_the_week_before fdbf(Monday);
date d = fdbf.get_date(date(2002,Feb,1));//2002-Jan-28
Function OverviewFunction PrototypeDescriptionExampledays days_until_weekday (const date&, const greg_weekday&) Calculates the number of days from given date until given weekday.
date d(2004,Jun,1); // Tuesday
greg_weekday gw(Friday);
days_until_weekday(d, gw); // 3 days
days days_before_weekday (const date&, const greg_weekday&) Calculates the number of day from given date to previous given weekday.
date d(2004,Jun,1); // Tuesday
greg_weekday gw(Friday);
days_before_weekday(d, gw); // 4 days
date next_weekday (const date&, const greg_weekday&) Generates a date object representing the date of the following weekday from the given date.
date d(2004,Jun,1); // Tuesday
greg_weekday gw(Friday);
next_weekday(d, gw); // 2004-Jun-4
date previous_weekday (const date&, const greg_weekday&) Generates a date object representing the date of the previous weekday from the given date.
date d(2004,Jun,1); // Tuesday
greg_weekday gw(Friday);
previous_weekday(d, gw); // 2004-May-28
topGregorian CalendarIntroduction --
Header --
FunctionsIntroduction
The class boost::gregorian::gregorian_calendar implements the functions necessary to create the gregorian date system. It converts to the year-month-day form of a date to a day number representation and back.
For most purposes this class is simply accessed by gregorian::date and is not used directly by the user. However, there are useful functions that might be of use such as the end_of_month_day function.
The print month example demonstrates this.
Header
#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o
or
#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types
FunctionsSyntaxDescriptionExamplestatic short day_of_week(ymd_type)Return the day of the week (0==Sunday, 1==Monday, etc)See also gregorian::date day_of_weekstatic date_int_type day_number(ymd_type) Convert a ymd_type into a day number. The day number is an absolute number of days since the epoch start.static short end_of_month_day(year_type, month_type)Given a year and month determine the last day of the month.static ymd_type from_day_number(date_int_type) Convert a day number to a ymd struct.static bool is_leap_year(year_type)Returns true if specified year is a leap year.gregorian_calendar::is_leap_year(2000) --> truetopClass day_clockClass day_clocktopPosix TimePosix Time SystemIntroduction --
Usage ExamplesIntroduction
Defines a non-adjusted time system with nano-second/micro-second resolution and stable calculation properties. The nano-second resolution option uses 96 bits of underlying storage for each ptime while the micro-second resolution uses 64 bits per ptime (see Build Options for details). This time system uses the Gregorian calendar to implement the date portion of the time representation.
Usage ExamplesExampleDescriptionTime MathA few simple calculations using ptime and time_durations.Print HoursRetrieve time from clock, use a time_iterator.Local to UTC ConversionDemonstrates a couple different ways to convert a local to UTC time including daylight savings rules.Time PeriodsSome simple examples of intersection and display of time periods.Ptime ClassIntroduction --
Header --
Construction --
Construct from String --
Construct from Clock --
Construct using Conversion functions --
Accessors --
Conversion To String --
OperatorsIntroduction
The class boost::posix_time::ptime is the primary interface for time point manipulation. In general, the ptime class is immutable once constructed although it does allow assignment.
Class ptime is dependent on gregorian::date for the interface to the date portion of a time point.
Other techniques for creating times include time iterators.
Header
#include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o
or
#include "boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types
ConstructionSyntaxDescriptionExampleptime(date,time_duration)Construct from a date and offset
ptime t1(date(2002,Jan,10), time_duration(1,2,3));
ptime t2(date(2002,Jan,10), hours(1)+nanosec(5));
ptime(ptime)Copy constructorptime t3(t1)ptime(special_values sv)Constructor for infinities, not-a-date-time, max_date_time, and min_date_time
ptime d1(neg_infin);
ptime d2(pos_infin);
ptime d3(not_a_date_time);
ptime d4(max_date_time);
ptime d5(min_date_time);ptime;Default constructor. Creates a ptime object initialized to not_a_date_time. NOTE: this constructor can be disabled by defining DATE_TIME_NO_DEFAULT_CONSTRUCTOR (see compiler_config.hpp)ptime p; // p => not_a_date_timeConstruct from StringSyntaxDescriptionExampleptime time_from_string(const std::string&)From delimited string.std::string ts("2002-01-20 23:59:59.000");
ptime t(time_from_string(ts))ptime from_iso_string(const std::string&)From non delimited iso form string.std::string ts("20020131T235959");
ptime t(from_iso_string(ts))Construct from ClockSyntaxDescriptionExamplestatic ptime second_clock::local_time();Get the local time, second level resolution, based on the time zone settings of the computer.ptime t(second_clock::local_time())static ptime second_clock::universal_time()Get the UTC time.ptime t(second_clock::universal_day())static ptime microsec_clock::local_time()Get the local time using a subsecond resolution clock. On Unix systems this is implemented using GetTimeOfDay. On most Win32 platforms it is implemented using ftime. Win32 systems often do not achieve microsecond resolution via this API. If higher resolution is critical to your application test your platform to see the acheived resolution.ptime t(microsec_clock::local_time())Construct using Conversion FunctionsSyntaxDescriptionExampleptime from_time_t(time_t t);Converts a time_t into a ptime.ptime t = from_time_t(tt);ptime from_ftime<ptime>(FILETIME ft);Creates a ptime object from a FILETIME structure.ptime t = from_ftime<ptime>(ft);AccessorsSyntaxDescriptionExampledate date() constGet the date part of a time.
date d(2002,Jan,10);
ptime t(d, hour(1));
t.date() --> 2002-Jan-10;
time_duration time_of_day() constGet the time offset in the day.
date d(2002,Jan,10);
ptime t(d, hour(1));
t.time_of_day() --> 01:00:00;
Conversion to StringSyntaxDescriptionExamplestd::string to_simple_string(ptime)To YYYY-mmm-DD HH:MM:SS.fffffffff string where mmm 3 char month name. Fractional seconds only included if non-zero.2002-Jan-01 10:00:01.123456789std::string to_iso_string(ptime)Convert to form YYYYMMDDTHHMMSS,fffffffff where T is the date-time separator20020131T100001,123456789std::string to_iso_extended_string(ptime)Convert to form YYYY-MM-DDTHH:MM:SS,fffffffff where T is the date-time separator2002-01-31T10:00:01,123456789OperatorsSyntaxDescriptionExample
operator==, operator!=,
operator>, operator<
operator>=, operator<=
A full complement of comparison operatorst1 == t2, etcptime operator+(date_duration) constReturn a ptime adding a day offset
date d(2002,Jan,1);
ptime t(d,minutes(5));
date_duration dd(1);
ptime t2 = t + dd;
ptime operator-(date_duration) constReturn a ptime subtracting a day offset
date d(2002,Jan,1);
ptime t(d,minutes(5));
date_duration dd(1);
ptime t2 = t - dd;
ptime operator+(time_duration) constReturn a ptime adding a time duration
date d(2002,Jan,1);
ptime t(d,minutes(5));
ptime t2 = t + hours(1) + minutes(2);
ptime operator-(time_duration) constReturn a ptime subtracting a time duration
date d(2002,Jan,1);
ptime t(d,minutes(5));
ptime t2 = t - minutes(2);
time_duration operator-(ptime) constTake the difference between two times.
date d(2002,Jan,1);
ptime t1(d,minutes(5));
ptime t2(d,seconds(5));
time_duration t3 = t2 - t1;//negative result
topTime DurationIntroduction --
Header --
Construction --
Count Based Construction --
Construct from String --
Accessors --
Conversion To String --
OperatorsIntroduction
The class boost::posix_time::time_duration the base type responsible for representing a length of time. A duration can be either positive or negative. The general time_duration class provides a constructor that takes a count of the number of hours, minutes, seconds, and fractional seconds count as shown in the code fragment below. The resolution of the time_duration is configureable at compile time. See Build-Compiler Information for more information.
using namespace boost::posix_time;
time_duration td(1,2,3,4); //01:02:03.000000004 when resolution is nano seconds
time_duration td(1,2,3,4); //01:02:03.000004 when resolution is micro seconds
Several small helper classes that derive from a base time_duration, as shown below, to adjust for different resolutions. These classes can shorten code and make the intent clearer.
As an example:
using namespace boost::posix_time;
time_duration td = hours(1) + seconds(10); //01:00:01
td = hours(1) + nanosec(5); //01:00:00.000000005
Note that the existence of the higher resolution classes (eg: nanosec) depends on the installation of the library. See Build-Compiler Information for more information.
Header
#include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o
or
#include "boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types
ConstructionSyntaxDescriptionExampletime_duration(hours,minutes,seconds,fractional_seconds)Construct ad duration from the countstime_duration td(1,2,3,9); //1 hr 2 min 3 sec 9 nanosecondsCount Based ConstructionSyntaxDescriptionExamplehours(long)Number of hourstime_duration td = hours(3);minutes(long)Number of minutestime_duration td = minutes(3);seconds(long) Number of secondstime_duration td = seconds(3);millisec(long)Number of milliseconds.time_duration td = millisec(3);microsec(long)Number of microseconds.time_duration td = microsec(3);nanosec(long)Number of nanoseconds.time_duration td = nanosec(3);Construct from StringSyntaxDescriptionExampletime_duration duration_from_string(const std::string&)From delimited string.
std::string ts("23:59:59.000");
time_duration td(duration_from_string(ts))
AccessorsSyntaxDescriptionExamplelong hours() constGet the number of normalized hours.time_duration td(1,2,3); td.hours() --> 1long minutes() constGet the number of minutes normalized (0..59).time_duration td(1,2,3); td.minutes() --> 2long seconds() constGet the normalized number of second (0..59).time_duration td(1,2,3); td.seconds() --> 3long total_seconds() constGet the total number of seconds truncating any fractional seconds.
time_duration td(1,2,3,10);
td.total_seconds() --> (1*3600) + (2*60) + 3 == 3723
long fractional_seconds() constGet the number of fractional seconds.time_duration td(1,2,3, 1000); td.fractional_seconds() --> 1000bool is_negative() constTrue if duration is negative.time_duration td(-1,0,0); td.is_negative() --> truetime_duration invert_sign() constGenerate a new duration with the sign inverted/time_duration td(-1,0,0); td.invert_sign() --> 01:00:00static boost::date_time::time_resolutions resolution()Describes the resolution capability of the time_duration class. time_resolutions is an enum of resolution possibilities ranging from seconds to nanoseconds.time_duration::resolution() --> nanostatic time_duration::num_fractional_digits()Returns an unsigned short holding the number of fractional digits the time resolution has.time_duration::num_fractional_digits(); // 9 for nano, 6 for micro, etc.boost::int64_t ticks()Return the raw count of the duration type.time_duration td(0,0,0, 1000); td.ticks() --> 1000static time_duration unit()Return smallest possible unit of duration type (1 nanosecond).time_duration::unit() --> time_duration(0,0,0,1)Conversion To StringSyntaxDescriptionExamplestd::string to_simple_string(time_duration)To HH:MM:SS.fffffffff were fff is fractional seconds that are only included if non-zero.10:00:01.123456789std::string to_iso_string(time_duration)Convert to form HHMMSS,fffffffff.100001,123456789OperatorsSyntaxDescriptionExample
operator==, operator!=,
operator>, operator<
operator>=, operator<=
A full complement of comparison operatorsdd1 == dd2, etctime_duration operator+(time_duration) constAdd durations.
time_duration td1(hours(1)+minutes(2));
time_duration td2(seconds(10));
time_duration td3 = td1 + td2;
time_duration operator-(time_duration) constSubtract durations.
time_duration td1(hours(1)+nanosec(2));
time_duration td2 = td1 - minutes(1);
time_duration operator/(int) constDivide the length of a duration by an integer value. Discards any remainder.
hours(3)/2 == time_duration(1,30,0);
nanosec(3)/2 == nanosec(1)
time_duration operator*(int) constMultiply the length of a duration by an integer value.hours(3)*2 == hours(6);topTime PeriodIntroduction --
Header --
Construction --
Accessors --
Conversion To String --
OperatorsIntroduction
The class boost::posix_time::time_period provides direct representation for ranges between two times. Periods provide the ability to simplify some types of calculations by simplifying the conditional logic of the program.
The time periods example provides an example of using time periods.
Header
#include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o
or
#include "boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types
ConstructionSyntaxDescriptionExampletime_period(ptime begin, ptime end) Create a period as [begin, end). If last is <= begin then the period will be defined as null.
date d(2002,Jan,01);
ptime t(d, seconds(10)); //10 sec after midnight
time_period tp(t, hours(3));
time_period(ptime start, time_duration len) Create a period as [begin, begin+len). If len is <= zero then the period will be defined as null.
date d(2002,Jan,01);
ptime t1(d, seconds(10)); //10 sec after midnight
ptime t2(d, hours(10)); //10 hours after midnight
time_period tp(t1, t2);
time_period(time_period rhs) Copy constructortime_period tp1(tp)AccessorsSyntaxDescriptionExampleptime begin() constReturn first time of period.
date d(2002,Jan,01);
ptime t1(d, seconds(10)); //10 sec after midnight
ptime t2(d, hours(10)); //10 hours after midnight
time_period tp(t1, t2); tp.begin() --> 2002-Jan-01 00:00:10
ptime last() constReturn last time in the period
date d(2002,Jan,01);
ptime t1(d, seconds(10)); //10 sec after midnight
ptime t2(d, hours(10)); //10 hours after midnight
time_period tp(t1, t2); tp.last() --> 2002-Jan-01 09:59:59.999999999
ptime end() const Return one past the last in period
date d(2002,Jan,01);
ptime t1(d, seconds(10)); //10 sec after midnight
ptime t2(d, hours(10)); //10 hours after midnight
time_period tp(t1, t2); tp.last() --> 2002-Jan-01 10:00:00
time_duration length() constReturn the length of the time period.
date d(2002,Jan,01);
ptime t1(d); //midnight
time_period tp(t1, hours(1));
tp.length() --> 1 hour
bool is_null() constTrue if period is not well formed. eg: start less than endbool contains(ptime) constTrue if ptime is within the period
date d(2002,Jan,01);
ptime t1(d, seconds(10)); //10 sec after midnight
ptime t2(d, hours(10)); //10 hours after midnight
ptime t3(d, hours(2)); //2 hours after midnight
time_period tp(t1, t2); tp.contains(t3) --> true
bool contains(time_period) constTrue if period is within the period
time_period tp1(ptime(d,hours(1)), ptime(d,hours(12)));
time_period tp2(ptime(d,hours(2)), ptime(d,hours(4)));
tp1.contains(tp2) --> true
tp2.contains(tp1) --> false
bool intersects(time_period) const True if periods overlap
time_period tp1(ptime(d,hours(1)), ptime(d,hours(12)));
time_period tp2(ptime(d,hours(2)), ptime(d,hours(4)));
tp2.intersects(tp1) --> true
time_period intersection(time_period) constCalculate the intersection of 2 periods. Null if no intersection.time_period merge(time_period) constReturns union of two periods. Null if no intersection.time_period span(time_period) constCombines two periods and any gap between them such that start = min(p1.start, p2.start) and end = max(p1.end , p2.end).time_period shift(date_duration)Add duration to both start and end.Conversion To StringSyntaxDescriptionExamplestd::string to_simple_string(time_period dp)To [YYYY-mmm-DD hh:mm:ss.fffffffff/YYYY-mmm-DD hh:mm:ss.fffffffff] string where mmm is 3 char month name.[2002-Jan-01 01:25:10.000000001/2002-Jan-31 01:25:10.123456789]OperatorsSyntaxDescriptionExampleoperator<<Output streaming operator for time duration. Uses facet to output [date time_of_day/date time_of_day]. The default is format is [YYYY-mmm-DD hh:mm:ss.fffffffff/YYYY-mmm-DD hh:mm:ss.fffffffff] string where mmm is 3 char month name.[2002-Jan-01 01:25:10.000000001/2002-Jan-31 01:25:10.123456789]operator==, operator!=Equality operators. Periods are equal if p1.begin == p2.begin && p1.last == p2.lastif (tp1 == tp2) {...operator<Ordering with no overlap. True if tp1.end() less than tp2.begin()if (tp1 < tp2) {...operator>Ordering with no overlap. True if tp1.begin() greater than tp2.end()if (tp1 > tp2) {... etcoperator<=, operator>=Defined in terms of the other operators.topTime IteratorsIntroduction --
Header --
Overview --
OperatorsIntroduction
Time iterators provide a mechanism for iteration through times. Time iterators are similar to Bidirectional Iterators. However, time_iterators are different than standard iterators in that there is no underlying sequence, just a calculation function. In addition, time_iterators are directly comparable against instances of class ptime. Thus a second iterator for the end point of the iteration is not required, but rather a point in time can be used directly. For example, the following code iterates using a 15 minute iteration interval. The print hours example also illustrates the use of the time_iterator.
#include "boost/date_time/posix_time/posix_time.hpp"
#include <iostream>
int
main()
{
using namespace boost::gregorian;
using namespace boost::posix_time;
date d(2000,Jan,20);
ptime start(d);
ptime end = start + hours(1);
time_iterator titr(start,minutes(15)); //increment by 15 minutes
//produces 00:00:00, 00:15:00, 00:30:00, 00:45:00
while (titr < end) {
std::cout << to_simple_string(*titr) << std::endl;
++titr;
}
std::cout << "Now backward" << std::endl;
//produces 01:00:00, 00:45:00, 00:30:00, 00:15:00
while (titr > start) {
std::cout << to_simple_string(*titr) << std::endl;
--titr;
}
}
Header
#include "boost/date_time/posix_time/posix_time.hpp" //include all types plus i/o
or
#include "boost/date_time/posix_time/posix_time_types.hpp" //no i/o just types
OverviewClassConstruction ParametersDescriptiontime_iteratorptime start_time, time_duration incrementIterate incrementing by the specified duration.OperatorsSyntaxDescriptionExample
operator==(const ptime& rhs),
operator!=(const ptime& rhs),
operator>, operator<
operator>=, operator<=
A full complement of comparison operators
date d(2002,Jan,1);
ptime start_time(d, hours(1));
//increment by 10 minutes
time_iterator titr(start_time, minutes(10));
ptime end_time = start_time + hours(2);
if (titr == end_time) // false
if (titr != end_time) // true
if (titr >= end_time) // false
if (titr <= end_time) // true
prefix incrementIncrement the iterator by the specified duration.
//increment by 10 milli seconds
time_iterator titr(start_time, milliseconds(10));
++titr; // == start_time + 10 milliseconds
prefix decrementDecrement the iterator by the specified time duration.Example time_iterator titr(start_time, time_duration(1,2,3));
--titr; // == start_time - 1 hour, 2 minutes, and 3 secondstopLocal Time AdjustmentIntroduction --
Header --
OverviewIntroduction
A frequent problem in time representation is the conversion between various local time systems. In general this is accomplished by using a reference time system. The reference time system is typically UTC.
Since the posix_time system does no internal time adjustment it can be used to represent both local times and UTC times. However, the user is currently left to handle conversions and time zone knowledge explicitly.
The library offers two different ways to perform UTC to local conversions. The first is using the time zone settings of the computer. This is a useful solution for converting a UTC time for a user machine. This approach depends on the ctime API and will provide incorrect results if the environment is set incorrectly. The other approach allows conversion from any zone to UTC and back independent of the settings of the time zone settings of the computer. The local utc conversion example demonstrates both of these techniques.
Header
#include "boost/date_time/gregorian/gregorian.hpp" //include all types plus i/o
or
#include "boost/date_time/gregorian/gregorian_types.hpp" //no i/o just types
OverviewClassDescriptionExampledate_time::c_local_adjustor<ptime>::utc_to_local(ptime)Calculate local machine time from a UTC time based on time zone settings and the C API.
typedef boost::date_time::c_local_adjustor<ptime> local_adj;
ptime t10(date(2002,Jan,1), hours(7));
ptime t11 = local_adj::utc_to_local(t10);
date_time::local_adjustor<ptime, utc_offset, dst_rules>::utc_to_local(ptime)Calculate local machine time from a UTC time based daylight savings rules and utc offsetexampledate_time::local_adjustor<ptime, utc_offset, dst_rules>::local_to_utc(ptime)Calculate UTC time based on daylight savings rules and utc offset.exampletopDetailsCalculationsTimepoints --
Durations --
Intervals (Periods) --
Special Value HandlingTimepoints
This section describes some of basic arithmetic rules that can be performed with timepoints. In general, Timepoints support basic arithmetic in conjunction with Durations as follows:
Timepoint + Duration --> Timepoint
Timepoint - Duration --> Timepoint
Timepoint - Timepoint --> Duration
Unlike regular numeric types, the following operations are undefined:
Duration + Timepoint --> Undefined
Duration - Timepoint --> Undefined
Timepoint + Timepoint --> Undefined
Durations
Durations represent a length of time and can have positive and negative values. It is frequently useful to be able to perform calculations with other durations and with simple integral values. The following describes these calculations:
Duration + Duration --> Duration
Duration - Duration --> Duration
Duration * Integer --> Duration
Integer * Duration --> Duration
Duration / Integer --> Duration (Integer Division rules)
Intervals (Periods)
Interval logic is extremely useful for simplifying many 'calculations' for dates and times. The following describes the operations provided by periods which are based on half-open range. The following operations calculate new time periods based on two input time periods:
Timeperiod intersection Timeperiod --> Timeperiod (null interval if no intersection)
Timeperiod merge Timeperiod --> Timeperiod (null interval if no intersection)
Timeperiod shift Duration --> Timeperiod (shift start and end by duration amount)
In addition, periods support various queries that calculate boolean results. The first set is caluculations with other time periods:
Timeperiod == Timeperiod --> bool
Timeperiod < Timeperiod --> bool (true if lhs.last <= rhs.begin)
Timeperiod intersects Timeperiod --> bool
Timeperiod contains Timeperiod --> bool
Timeperiod is_adjacent Timeperiod --> bool
The following calculations are performed versus the Timepoint.
Timeperiod contains Timepoint --> bool
Timeperiod is_before Timepoint --> bool
Timeperiod is_after Timepoint --> bool
Special Value Handling
For many temporal problems it is useful for Duration and Timepoint types to support special values such as Not A Date Time (NADT) and infinity. In general special values such as Not A Date Time (NADT) and infinity should follow rules like floating point values. Note that it should be possible to configure NADT based systems to throw an exception instead of result in NADT.
Timepoint(NADT) + Duration --> Timepoint(NADT)
Timepoint(∞) + Duration --> Timepoint(∞)
Timepoint + Duration(∞) --> Timepoint(∞)
Timepoint - Duration(∞) --> Timepoint(-∞)
When performing operations on both positive and negative infinities, the library will produce results consistent with the following.
Timepoint(+∞) + Duration(-∞) --> NADT
Duration(+∞) + Duration(-∞) --> NADT
Duration(±∞) * Zero --> NADT
Duration(∞) * Integer(Not Zero) --> Duration(∞)
Duration(+∞) * -Integer --> Duration(-∞)
Duration(∞) / Integer --> Duration(∞)
Design GoalsCategoryDescriptionFunctionsInterfacesProvide concrete classes for manipulation of dates and times
date, time, date_duration, time_duration, date_period, time_period, etc
support for infinity - positive infinity, negative infinity
iterators over time and date ranges
allow date and time implementations to be separate as much as possible
CalculationProvide a basis for performing efficient time calculations days between dates durations of times durations of dates and times together Representation FlexibilityProvide the maximum possible reusability and flexibility
traits based customization of internal
representations for size versus resolution control
Allowing the use of different epochs and resolution
(eg: seconds versus microseconds, dates starting at the
year 2000 versus dates starting in 1700)
Options for configuring unique calendar representations
(Gregorian + others)
the use of Julian Day number and the conversion between
this and the Gregorian/Julian calendar date
Allow for flexible adjustments including
leap seconds
Date CalculationsProvide tools for date calculationsprovide basis for calculation of complex event specs like holidayscalendar to calendar conversionsprovide for ability to extend to new calendar systemsTime CalculationsProvide concrete classes for manipulation of timeprovide the ability to handle cross time-zone issuesprovide adjustments for daylight savings time (summer time)Clock InterfacesProvide classes for retrieving time current timeaccess to a network / high resolution time sources retrieving the current date time information to populate classes I/O InterfacesProvide input and output for time includingmulti-lingual support provide ISO8601 compliant time facet use I/O facets for different local behavior Tradeoffs: Stability, Predictability, and Approximations
Unavoidable Trade-offs
The library does its best to provide everything a user could want, but there are certain inherent constraints that limit what any temporal library can do. Specifically, a user must choose which two of the following three capabilities are desired in any particular application:
exact agreement with wall-clock timeaccurate math, e.g. duration calculationsability to handle timepoints in the future
Some libraries may implicitly promise to deliver all three, but if you actually put them to the test, only two can be true at once. This limitation is not a deficiency in the design or implementation of any particular library; rather it is a consequence of the way different time systems are defined by international standards. Let's look at each of the three cases:
If you want exact agreement with wall-clock time, you must use either UTC or local time. If you compute a duration by subtracting one UTC time from another and you want an answer accurate to the second, the two times must not be too far in the future because leap seconds affect the count but are only determined about 6 months in advance. With local times a future duration calculation could be off by an entire hour, since legislatures can and do change DST rules at will.
If you want to handle wall-clock times in the future, you won't be able (in the general case) to calculate exact durations, for the same reasons described above.
If you want accurate calculations with future times, you will have to use TAI or an equivalent, but the mapping from TAI to UTC or local time depends on leap seconds, so you will not have exact agreement with wall-clock time.
Stability, Predictability, and Approximations
Here is some underlying theory that helps to explain what's going on. Remember that a temporal type, like any abstract data type (ADT), is a set of values together with operations on those values.
Stability
The representation of a type is stable if the bit pattern associated with a given value does not change over time. A type with an unstable representation is unlikely to be of much use to anyone, so we will insist that any temporal library use only stable representations.
An operation on a type is stable if the result of applying the operation to a particular operand(s) does not change over time.
Predictability
Sets are most often classified into two categories: well-defined and ill-defined. Since a type is a set, we can extend these definitions to cover types. For any type T, there must be a predicate is_member( x ) which determines whether a value x is a member of type T. This predicate must return true, false, or dont_know.
If for all x, is_member( x ) returns either true or false, we say the set T is well-defined.
If for any x, is_member( x ) returns dont_know, we say the set T is ill-defined.
Those are the rules normally used in math. However, because of the special characteristics of temporal types, it is useful to refine this view and create a third category as follows:
For any temporal type T, there must be a predicate is_member( x, t ) which determines whether a value x is a member of T. The parameter t represents the time when the predicate is evaluated. For each xi, there must be a time ti and a value v such that:
v = true or v = false, andfor all t < ti, is_member( xi, t ) returns dont_know, andfor all t >= ti, is_member( xi, t ) returns v.
ti is thus the time when we "find out" whether xi is a member of T. Now we can define three categories of temporal types:
If for all xi, ti = negative infinity, we say the type T is predictable.
If for some xi, ti = positive infinity, we say the type T is ill-formed.
Otherwise we say the type T is unpredictable (this implies that for some xi, ti is finite).
Ill-formed sets are not of much practical use, so we will not discuss them further. In plain english the above simply says that all the values of a predictable type are known ahead of time, but some values of an unpredictable type are not known until some particular time.
Stability of Operations
Predictable types have a couple of important properties:
there is an order-preserving mapping from their elements onto a set of consecutive integers, andduration operations on their values are stable
The practical effect of this is that duration calculations can be implemented with simple integer subtraction. Examples of predictable types are TAI timepoints and Gregorian dates.
Unpredictable types have exactly the opposite properties:
there is no order-preserving mapping from their elements onto a set of consecutive integers, andduration operations on their values are not stable.
Examples of unpredictable types are UTC timepoints and Local Time timepoints.
We can refine this a little by saying that a range within an unpredicatable type can be predictable, and operations performed entirely on values within that range will be stable. For example, the range of UTC timepoints from 1970-01-01 through the present is predictable, so calculations of durations within that range will be stable.
Approximations
These limitations are problematical, because important temporal types like UTC and Local Time are in fact unpredictable, and therefore operations on them are sometimes unstable. Yet as a practical matter we often want to perform this kind of operation, such as computing the duration between two timepoints in the future that are specified in Local Time.
The best the library can do is to provide an approximation, which is generally possible and for most purposes will be good enough. Of course the documentation must specify when an answer will be approximate (and thus unstable) and how big the error may be. In many respects calculating with unpredictable sets is analogous to the use of floating point numbers, for which results are expected to only be approximately correct. Calculating with predictable sets would then be analogous to the user of integers, where results are expected to be exact.
For situations where exact answers are required or instability cannot be tolerated, the user must be able to specify this, and then the library should throw an exception if the user requests a computation for which an exact, stable answer is not possible.
Serialization
The boost::date_time library is compatible with the boost::serialization library's text and xml archives. The list of classes that are serializable are:
boost::gregoriandatedate_durationdate_periodpartial_datenth_day_of_week_in_monthfirst_day_of_week_in_monthlast_day_of_week_in_monthfirst_day_of_week_beforefirst_day_of_week_aftergreg_monthgreg_daygreg_weekdayboost::posix_timeptimetime_durationtime_period
No extra steps are required to build the date_time library for serialization use.
Example text_archive usage:
using namespace boost::posix_time;
using namespace boost::gregorian;
ptime pt(date(2002, Feb, 14)), hours(10)), pt2(not_a_date_time);
std::ofstream ofs("tmp_file");
archive::test_oarchive oa(ofs);
oa << pt; // NOTE: no macro
ofs.close();
std::ifstream ifs("tmp_file");
archive::text_iarchive ia(ifs);
ia >> pt2; // NOTE: no macro
ifs.close();
pt == pt2; // true
Example xml_archive usage:
using namespace boost::gregorian;
date d(2002, Feb, 14), d2(not_a_date_time);
std::ofstream ofs("tmp_file");
archive::xml_oarchive oa(ofs);
oa << BOOST_SERIALIZATION_NVP(d); // macro required for xml_archive
ofs.close();
std::ifstream ifs("tmp_file");
archive::xml_iarchive ia(ifs);
ia >> BOOST_SERIALIZATION_NVP(d2); // macro required for xml_archive
ifs.close();
d == d2; // true
To use the date_time serialization code, the proper header files must be explicitly included. The header files are:
boost/date_time/gregorian/greg_serialize.hpp
and
boost/date_time/posix_time/time_serialize.hppTerminology
The following are a number of terms relevant to the date-time domain.
A taxonomy of temporal types:
Timepoint -- Specifier for a location in the time continuum. Similar to a number on a ruler.Timelength -- A duration of time unattached to any point on the time continuum.Timeinterval -- A duration of time attached to a specific point in the time continuum.
And some other terms:
Accuracy -- A measure of error, the difference between the reading of a clock and the true time.Calendar System -- A system for labeling time points with day level resolution.Clock Device -- A software component (tied to some hardware) that provides the current date or time with respect to a calendar or clock system.Precision -- A measure of repeatability of a clock.Resolution -- A specification of the smallest representable duration (eg: 1 second, 1 century) for a clock/calendar system or temporal type.Stability -- The property of a class which says that the underlying representation (implementation) associated with a particular (abstract) value will never change.Time System -- A system for labeling time points with higher resolution than day-level.
Some standard date-time terminology:
Epoch -- Starting time point of a calendar or clock system.DST -- Daylight savings time - a local time adjustment made in some regions during the summer to shift the clock time of the daylight hoursTime zone -- A region of the earth that provides for a 'local time' defined by DST rules and UT offset.UTC Time -- Coordinated Universal Time - Civil time system as measured at longitude zero. Kept adjusted to earth rotation by use of leap seconds. Also known as Zulu Time. Replaced the similar system known as Greenwich Mean Time. For more see TAI Time -- A high-accuracy monotonic (need better term) time system measured to .1 microsecond resolution by atomic clocks around the world. Not adjusted to earth rotation. For more see
Some more experimental ones:
Local Time -- A time measured in a specific location of the universe.Time Label -- A tuple that either completely or partially specifies a specific date-time with respect to a calendar or clock system. This is the year-month-day representation.Adjusting Time Length -- A duration that represents varying physical durations depending on the moment in time. For example, a 1 month duration is typically not a fixed number of days and it depends on the date it is measured from to determine the actual length.
These are design sorts of terms:
Generation function -- A function that generates a specific set of time points, lengths, or intervals based on one or more parameters. ReferencesDate ReferencesTime ReferencesOther C/C++ LibrariesJAVA Date-Time LibrariesScripting Language LibrariesRelated Commercial and Fanciful PagesResolution, Precision, and AccuracyDate Calendar ReferencesISO 8601 date time standard -- Summary by Markus KuhnCalendrical Calculations book by Reingold & DershowitzCalendar FAQ by Claus TønderingCalendar zone XML schema for date timeWill Linden's Calendar LinksXMAS calendar meltTimeMartin Folwer on time patterns
Recurring Events for CalendarsPatterns for things that Change with timeUS National Institute of Standards and Technology Time ExhibitsNetwork Time Protocol at NTP.orgUS Navy Systems of TimeInternational Atomic TimeDate-Time type PostgreSQL User Guide Other C/C++ Librariesctime C Standard library reference at cplusplus.comXTime C extension proposalAnother C library extension proposal by David TribblelibTAI is a C based time libraryTime Zone Database C library for managing timezones/placesInternational Components for Unicode by IBM (open source)
Calendar ClassDate Time ServicesTime Zone ClassDate-Time FormattingJulian Library in C by Mark Showalter -- NASAJAVA Date & Time Library Quick ReferenceCalendar classGregorian calendarDate classsql.time classDate format symbolsDate formatSimple Date FormatSimple Time ZoneScripting Language LibrariesA python date library MX Date TimePerl date-time
Date-Time packages at CPANDate::Calc at CPANDate::Convert calendar conversions at CPANA PHP library Vlib Date LibraryRelated Commercial and Fanciful PagesLeapsecond.com time pageWorld Time Server / TZ database10000 year clock at Long Now FoundationTimezones for PCsResolution, Precision, and AccuracyDefinitions with pictures from Agilent TechnologiesAnother set of pictures from Team LabsDefinitions from Southampton InstituteDefinitions from Newport Corporation in the context of instrumentationBuild-Compiler InformationOverview --
Compilation Options --
Compiler/Portability Notes --
Directory Structure --
Required Boost LibrariesOverview
The library has several functions that require the creation of a library file. The Jamfile in the build directory will produce a "static" library (libboost_date_time) and a "dynamic/shared" library (boost_date_time) that contains these functions.
Compilation Options
By default the posix_time system uses a 64 bit integer and a 32 bit integer internally to provide nano-second level resolutions. As an alternative, a single 64 bit integer can be used to provide a microsecond level resolution. This alternative implementation may provide better performance and more compact memory usage for many applications that do not require nano-second resolutions.
To use the alternate resolution (64 bit microsecond) the variable BOOST_DATE_TIME_POSIX_TIME_STD_CONFIG must be defined in the library users project files (ie Makefile, Jamfile, etc). This macro is not used by the Gregorian system and therefore has no effect when building the library.
Compiler/Portability Notes
The Boost Date-Time library has been built and tested with many compilers. However, some compilers and standard libraries have issues. While some of these issues can be worked around, others are difficult to work around. The following compilers fully support all aspects of the library:
GCC 3.2-7 on LinuxGCC 2.95.3 with STLport-4.5.3 on LinuxGCC 3.1 (cygwin)MSVC 7.1
In particular, a lack of support for standard locales limits the ability of the library to support iostream based input output. For these compilers a set of more limited string based input-output is provided. The compilers/standard libraries with this limitation include:
GCC 2.9x on LinuxBorland 5.1.1 and 5.6MSVC 6 SP5
Other compilers such as Comeau and Metroworks have been tested successfully with earlier versions of the library.
Directory Structure
The directory tree has the following structure:
/boost/date_time -- common headers and template code
/boost/date_time/gregoran -- Gregorian calendar system header files
/boost/date_time/posix_time -- posix time system headers
/libs/date_time/build -- build files and output directory
/libs/date_time/test -- test battery for generic code
/libs/date_time/test/gregorian -- test battery for the Gregorian system
/libs/date_time/test/posix_time -- test battery for the posix_time system
/libs/date_time/examples/posix_time -- time example programs
/libs/date_time/examples/gregorian -- nifty example programs
/libs/date_time/src/gregorian -- cpp files for libboost_date_time
/libs/date_time/src/posix_time -- empty (one file, but no source code...)
Required Boost Libraries
The library depends on
boost.tokenizerboost.integer(cstdint)boost.operatorsboost::lexical_cast
so at least these libraries need to be installed.
Tests
The library provides a large number of tests in the
libs/date_time/test
libs/date_time/test/gregorian
libs/date_time/test/posix_time
directories. Building and executing these tests assures that the installation is correct and that the library is functioning correctly. In addition, these tests facilitate the porting to new compilers. Finally, the tests provide examples of many functions not explicitly described in the usage examples.
Change HistoryChanges from Boost 1.31 to 1.32 (date_time 1.02 to 1.03)TypeDescriptionBug FixSnap to end of month behavior corrected for year_functor. Previously, starting
from 2000-Feb-28 (leap year and not end of month) and iterating through the next
leap year would result in 2004-Feb-29 instead of 2004-Feb-28. This behavior has
been corrected to produce the correct result of 2004-Feb-28. Thanks to Bart Garst
for this change.
FeatureFree function for creating a ptime object from a FILETIME struct. This function
is only available on platforms that define BOOST_HAS_FTIME.
FeatureMicrosecond time clock is now available on most windows compilers as well as
Unix.
FeatureUse of the boost::serialization library is now available with most of the
date_time classes. Classes capable of serialization are: date_generator classes,
date, days, date_period, greg_month, greg_weekday, greg_day, ptime, time_duration,
and time_period. Thanks to Bart Garst for this change.
FeatureFunctions added to convert date and time classes to wstring. The library now
provides to_*_wstring as well as to_*_string functions for: simple, iso,
iso_extended, and sql for dates and compilers that support wstrings. Thanks to
Bart Garst for this change.
FeaturePeriod classes now handle zero length and NULL periods correctly. A NULL period
is a period with a negative length. Thanks to Frank Wolf and Bart Garst for this
change.
FeatureAdded end_of_month function to gregorian::date to return the last day of
the current month represented by the date. Result is undefined for
not_a_date_time or infinities.
Bug FixRemoved incorrect usage of BOOST_NO_CWCHAR macro throughout library.
FeatureNew names added for some date classes. Original names are still valid but may
some day be deprecated. Changes are:
date_durationis nowdaysnth_kday_of_monthis nownth_day_of_the_week_in_monthfirst_kday_of_monthis nowfirst_day_of_the_week_in_monthlast_kday_of_monthis nowlast_day_of_the_week_in_monthfirst_kday_afteris nowfirst_day_of_the_week_afterfirst_kday_beforeis nowfirst_day_of_the_week_beforeFeatureFree functions for date generators added. Functions are: days_until_weekday, days_before_weekday, next_weekday, and previous_weekday.
days days_until_weekday(date, greg_weekday);
days days_before_weekday(date, greg_weekday);
date next_weekday(date, greg_weekday);
date previous_weekday(date, greg_weekday);
Thanks to Bart Garst for this change.
FeatureNew experimental duration types added for months, years, and weeks. These classes
also provide mathematical operators for use with date and time classes. Be aware
that adding of months or years a time or date past the 28th of a month may show
non-normal mathematical properties. This is a result of 'end-of-month'
snapping used in the calculation. The last example below illustrates the
issue.
months m(12);
years y(1);
m == y; // true
days d(7);
weeks w(1);
d == w; // true
ptime t(...);
t += months(3);
date d(2004,Jan,30);
d += months(1); //2004-Feb-29
d -= months(1); //2004-Jan-29
Input streaming is not yet implemented for these types.
Thanks to Bart Garst for this change.
FeatureUnifying base class for date_generators brought in to gregorian namespace. See Print Holidays Example.
FeatureAdded constructors for date and ptime that allow for default construction (both)
and special values construction (ptime, both now support this). Default
constructors initialize the objects to not_a_date_time (NADT).
ptime p_nadt(not_a_date_time), p_posinf(pos_infin);
ptime p; // p == NADT
date d; // d == NADT
Thanks to Bart Garst for this change.
FeatureOutput streaming now supports wide stream output on compiler / standard library combinations that support wide streams. This allows code like:
std::wstringstream wss;
date d(2003,Aug,21);
wss << d;
Thanks to Bart Garst for this change.
FeatureInput streaming for date and time types is now supported on both wide and narrow streams:
date d(not_a_date_time);
std::stringstream ss("2000-FEB-29");
ss >> d; //Feb 29th, 2000
std::wstringstream ws("2000-FEB-29");
ws >> d; //Feb 29th, 2000
Thanks to Bart Garst for this change.
Bug Fix Fixed bug in duration_from_string() where a string formatted with
less than full amount of fractional digits created an incorrect
time_duration. With microsecond resolution for time durations
the string "1:01:01.010" created a time duration of
01:01:01.000010 instead of 01:01:01.010000
Bug FixFixed the special value constructor for gregorian::date and posix_time::ptime
when constructing with min_date_time or max_date_time. The wrong value was
constructed for these.
Changes from Boost 1.30 to 1.31 (date_time 1.01 to 1.02)TypeDescriptionBug FixBuild configuration updated so dll, statically, and dynamically linkable library files are now produced with MSVC compilers. See Build/Compiler Information for more details.Bug FixTime_duration from_string is now correctly constructed from a negative value. (ie "-0:39:00.000") Code provided by Bart Garst.Bug FixFixed many MSVC compiler warnings when compiled with warning level 4.FeatureAdded prefix decrement operator (--) for date and time iterators. See Time Iterators and Date Iterators for more details. Code provided by Bart Garst.FeatureSpecial_values functionality added for date_duration, time_duration and time classes. Code provided by Bart Garst.Bug FixFixed time_duration_traits calculation bug which was causing time duration to be limited to 32bit range even when 64 bits were available. Thanks to Joe de Guzman for tracking this down.Bug FixProvided additional operators for duration types (eg: date_duration, time_duration). This includes dividable by integer and fixes to allow +=, -= operators. Thanks to Bart Garst for writing this code. Also, the documentation of Calculations has been improved.Bug FixAdded typedefs to boost::gregorian gregorian_types.hpp various date_generator function classes.FeatureAdded from_time_t function to convert time_t to a ptime.FeatureAdded a span function for combining periods. See date period and time period docs.FeatureAdded a function to time_duration to get the total number of seconds in a
duration truncating any fractional seconds. In addition, other resolutions
were added to allow for easy conversions. For example
seconds(1).total_milliseconds() == 1000
seconds(1).total_microseconds() == 1000000
hours(1).total_milliseconds() == 3600*1000 //3600 sec/hour
seconds(1).total_nanoseconds() == 1000000000
FeatureAdded output streaming operators for the date generator classes - partial_date, first_kday_after, first_kday_before, etc. Thanks to Bart Garst for this work.FeatureAdded unary- operators for durations for reversing the sign of a time duration. For example:
time_duration td(5,0,0); //5 hours
td = -td; //-5 hours
Thanks to Bart Garst for this work.FeatureAdded support for parsing strings with 'month names'. Thus creating a date object from string now accepts multiple formats ("2003-10-31","2003-Oct-31", and "2003-October-31"). Thus, date d = from_simple_string("2003-Feb-27") is now allowed. A bad month name string ( from_simple_string("2003-SomeBogusMonthName-27")) will cause a bad_month exception. On most compilers the string compare is case insensitive. Thanks to Bart Garst for this work.FeatureIn addition to support for month names or numbers, functions have been added to create date objects from multi-ordered date strings. Ex: "January-21-2002", "2002-Jan-21", and "21-Jan-2003". See Date Class for more details.Bug-FixVarious documentation fixes. Thanks to Bart Garst for updates.Changes from Boost 1.29 to 1.30 (date_time 1.00 to 1.01)
Notice: The interface to the partial_date class (see date_algorithms) was changed. The order of construction parameters was changed which will cause some code to fail execution. This change was made to facilitate more generic local time adjustment code. Thus instead of specifying partial_date pd(Dec,25) the code needs to be changed to partial_date pd(25, Dec);
TypeDescriptionBug FixAdded new experimental feature for Daylight Savings Time calculations. This allows traits based specification of dst rules.FeatureAdded new interfaces to calculate julian day and modified julian day to the gregorian date class. See boost::gregorian::date.FeatureAdd new interface to calculate iso 8601 week number for a date. See boost::gregorian::date.FeatureAdd an iso 8601 time date-time format (eg: YYYYMMDDTHHHMMSS) parsing function. See Class ptime for more information.Feature Added a length function to the period template so that both date_periods and time_periods will now support this function.Bug FixSplit Jamfiles so that libs/date_time/build/Jamfile only builds library and /libs/date_time/libs/test/Jamfile which runs tests.Bug FixFixed many minor documentation issues.Bug FixRemoved the DATE_TIME_INLINE macro which was causing link errors. This macro is no longer needed in projects using the library.Bug FixAdded missing typedef for year_iterator to gregorian_types.hppBug FixFixed problem with gregorian ostream operators that prevented the use of wide streams.Bug-FixTighten error handling for dates so that date(2002, 2, 29) will throw a bad_day_of_month exception. Previously the date would be incorrectly constructed. Reported by sourceforge bug: 628054 among others.Acknowledgements
Many people have contributed to the development of this library. In particular Hugo Duncan and Joel de Guzman for help with porting to various compilers. For initial development of concepts and design Corwin Joy and Michael Kenniston deserve special thanks. Also extra thanks to Michael for writing up the theory and tradeoffs part of the documentation. Dave Zumbro for initial inspiration and sage thoughts. Many thanks to boost reviewers and users including: William Seymour, Kjell Elster, Beman Dawes, Gary Powell, Andrew Maclean, William Kempf, Peter Dimov, Chris Little, David Moore, Darin Adler, Gennadiy Rozental, Joachim Achtzehnter, Paul Bristow, Jan Langer, Mark Rodgers, Glen Knowles, Matthew Denman, and George Heintzelman.
ExamplesGeneral Usage Examples
The following provides some sample usage of dates.
See Date Programming
for more details.
using namespace boost::gregorian;
date weekstart(2002,Feb,1);
date weekend = weekstart + week(1);
date d2 = d1 + days(5);
date today = day_clock::local_day();
if (d2 >= today) {} //date comparison operators
date_period thisWeek(d1,d2);
if (thisWeek.contains(today)) {}//do something
//iterate and print the week
day_iterator itr(weekstart);
while (itr <= weekend) {
std::cout << (*itr) << std::endl;
++itr;
}
//input streaming
std::stringstream ss("2004-Jan-1");
ss >> d3;
//localized i/o using facets
std::locale global;
std::locale german(global,
new date_facet(de_short_month_names,
de_long_month_names,
de_special_value_names,
de_long_weekday_names,
de_long_weekday_names,
'.',
boost::date_time::ymd_order_dmy));
std::cout.imbue(global2);
date d4(2002, Oct, 1);
std::cout << d4; //01.Okt.2002
//date generator functions
date d5 = next_weekday(d4, Sunday); //calculate sunday following d4
//define a shorthand for the nth_day_of_the_week_in_month function object
typedef nth_day_of_the_week_in_month nth_dow;
//US labor day is first Monday in Sept
nth_dow labor_day(nth_dow::first,Monday, Sep);
date d6 = labor_day.get_date(2004); //calculate a specific date from functor
The following provides some example code using times.
See Time Programming
for more details.
use namespace boost::posix_time;
date d(2002,Feb,1); //an arbitrary date
ptime t1(d, hours(5)+nanosec(100)); //date + time of day offset
ptime t2 = t1 - minutes(4)+seconds(2);
ptime now = second_clock::local_time(); //use the clock
date today = now.date(); //Get the date part out of the time
date tommorrow = today + date_duration(1);
ptime tommorrow_start(tommorrow); //midnight
//input streaming
std::stringstream ss("2004-Jan-1 05:21:33.20");
ss >> t2;
//starting at current time iterator adds by one hour
time_iterator titr(now,hours(1));
for (; titr < tommorrow_start; ++titr) {
std::cout << (*titr) << std::endl;
}
topDates as Strings
Various parsing and output of strings.
/* The following is a simple example that shows conversion of dates
* to and from a std::string.
*
* Expected output:
* 2001-Oct-09
* 2001-10-09
* Tuesday October 9, 2001
* An expected exception is next:
* Exception: Month number is out of range 1..12
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <iostream>
#include <string>
int
main()
{
using namespace boost::gregorian;
try {
// The following date is in ISO 8601 extended format (CCYY-MM-DD)
std::string s("2001-10-9"); //2001-October-09
date d(from_simple_string(s));
std::cout << to_simple_string(d) << std::endl;
//Read ISO Standard(CCYYMMDD) and output ISO Extended
std::string ud("20011009"); //2001-Oct-09
date d1(from_undelimited_string(ud));
std::cout << to_iso_extended_string(d1) << std::endl;
//Output the parts of the date - Tuesday October 9, 2001
date::ymd_type ymd = d1.year_month_day();
greg_weekday wd = d1.day_of_week();
std::cout << wd.as_long_string() << " "
<< ymd.month.as_long_string() << " "
<< ymd.day << ", " << ymd.year
<< std::endl;
//Let's send in month 25 by accident and create an exception
std::string bad_date("20012509"); //2001-??-09
std::cout << "An expected exception is next: " << std::endl;
date wont_construct(from_undelimited_string(bad_date));
//use wont_construct so compiler doesn't complain, but you wont get here!
std::cout << "oh oh, you shouldn't reach this line: "
<< to_iso_string(wont_construct) << std::endl;
}
catch(std::exception& e) {
std::cout << " Exception: " << e.what() << std::endl;
}
return 0;
}
topDays Alive
Calculate the number of days you have been living using durations and dates.
/* Short example that calculates the number of days since user was born.
* Demonstrates comparisons of durations, use of the day_clock,
* and parsing a date from a string.
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <iostream>
int
main()
{
using namespace boost::gregorian;
std::string s;
std::cout << "Enter birth day YYYY-MM-DD (eg: 2002-02-01): ";
std::cin >> s;
try {
date birthday(from_simple_string(s));
date today = day_clock::local_day();
days days_alive = today - birthday;
days one_day(1);
if (days_alive == one_day) {
std::cout << "Born yesterday, very funny" << std::endl;
}
else if (days_alive < days(0)) {
std::cout << "Not born yet, hmm: " << days_alive.days()
<< " days" <<std::endl;
}
else {
std::cout << "Days alive: " << days_alive.days() << std::endl;
}
}
catch(...) {
std::cout << "Bad date entered: " << s << std::endl;
}
return 0;
}
topDays Between New Years
Calculate the number of days till new years
/* Provides a simple example of using a date_generator, and simple
* mathematical operatorations, to calculate the days since
* New Years day of this year, and days until next New Years day.
*
* Expected results:
* Adding together both durations will produce 366 (365 in a leap year).
*/
#include <iostream>
#include "boost/date_time/gregorian/gregorian.hpp"
int
main()
{
using namespace boost::gregorian;
date today = day_clock::local_day();
partial_date new_years_day(1,Jan);
//Subtract two dates to get a duration
days days_since_year_start = today - new_years_day.get_date(today.year());
std::cout << "Days since Jan 1: " << days_since_year_start.days()
<< std::endl;
days days_until_year_start = new_years_day.get_date(today.year()+1) - today;
std::cout << "Days until next Jan 1: " << days_until_year_start.days()
<< std::endl;
return 0;
};
topEnd of the Months
Iterates accross the remaining months in a given year, always landing on the last day of the month.
/* Simple program that uses the gregorian calendar to find the last
* day of the month and then display the last day of every month left
* in the year.
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <iostream>
int
main()
{
using namespace boost::gregorian;
std::cout << " Enter Year(ex: 2002): ";
int year, month;
std::cin >> year;
std::cout << " Enter Month(1..12): ";
std::cin >> month;
try {
int day = gregorian_calendar::end_of_month_day(year,month);
date end_of_month(year,month,day);
//Iterate thru by months --
month_iterator mitr(end_of_month,1);
date start_of_next_year(year+1, Jan, 1);
//loop thru the days and print each one
while (mitr < start_of_next_year){
std::cout << to_simple_string(*mitr) << std::endl;
++mitr;
}
}
catch(...) {
std::cout << "Invalid Date Entered" << std::endl;
}
return 0;
}
topLocalization Demonstration
The boost::date_time library provides the ability to create customized locale facets. Date ordering, language, seperators, and abbreviations can be customized.
/* The following shows the creation of a facet for the output of
* dates in German (please forgive me for any errors in my German --
* I'm not a native speaker).
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <iostream>
/* Define a series of char arrays for short and long name strings to be
* associated with date output. */
const char* const de_short_month_names[] =
{
"Jan", "Feb", "Mar", "Apr", "Mai", "Jun",
"Jul", "Aug", "Sep", "Okt", "Nov", "Dez", "NAM"
};
const char* const de_long_month_names[] =
{
"Januar", "Februar", "Marz", "April", "Mai",
"Juni", "Juli", "August", "September", "Oktober",
"November", "Dezember", "NichtDerMonat"
};
const char* const de_special_value_names[] =
{
"NichtDatumzeit", "-unbegrenztheit", "+unbegrenztheit"
};
const char* const de_long_weekday_names[] =
{
"Sonntag", "Montag", "Dienstag", "Mittwoch",
"Donnerstag", "Freitag", "Samstag"
};
const char* const de_short_weekday_names[] =
{
"Son", "Mon", "Die","Mit", "Don", "Fre", "Sam"
};
const char* const us_short_month_names[] =
{
"Jan", "Feb", "Mar", "Apr", "May", "Jun",
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec", "NAD"
};
const char* const us_long_month_names[] =
{
"January", "February", "March", "April", "May",
"June", "July", "August", "September", "October",
"November", "December", "Not-A-Date"
};
const char* const us_special_value_names[] =
{
"Not-A-Date", "-infinity", "+infinity"
};
const char* const us_long_weekday_names[] =
{
"Sunday", "Monday", "Tuesday", "Wenesday",
"Thursday", "Friday", "Saturday"
};
const char* const us_short_weekday_names[] =
{
"Sun", "Mon", "Tue","Wed", "Thu", "Fri", "Sat"
};
int
main()
{
#ifndef BOOST_DATE_TIME_NO_LOCALE
using namespace boost::gregorian;
typedef boost::date_time::all_date_names_put<greg_facet_config> date_facet;
//create a new local
std::locale default_locale;
std::locale german_dates1(default_locale,
new date_facet(de_short_month_names,
de_long_month_names,
de_special_value_names,
de_short_weekday_names,
de_long_weekday_names,
'.',
boost::date_time::ymd_order_dmy,
boost::date_time::month_as_integer));
date d1(2002, Oct, 1);
std::cout.imbue(german_dates1);
// output the date in German using short month names
std::cout << d1 << std::endl; //01.10.2002
std::locale german_dates2(default_locale,
new date_facet(de_short_month_names,
de_long_month_names,
de_special_value_names,
de_short_weekday_names,
de_long_weekday_names,
'.',
boost::date_time::ymd_order_dmy,
boost::date_time::month_as_long_string));
std::cout.imbue(german_dates2);
greg_month m = d1.month();
std::cout << m << std::endl; //Oktober
greg_weekday wd = d1.day_of_week();
std::cout << wd << std::endl; //Dienstag
//Numeric date format with US month/day/year ordering
std::locale usa_dates1(default_locale,
new date_facet(us_short_month_names,
us_long_month_names,
us_special_value_names,
us_short_weekday_names,
us_long_weekday_names,
'/',
boost::date_time::ymd_order_us,
boost::date_time::month_as_integer));
std::cout.imbue(usa_dates1);
std::cout << d1 << std::endl; // 10/01/2002
//English names, iso order (year-month-day), '-' separator
std::locale usa_dates2(default_locale,
new date_facet(us_short_month_names,
us_long_month_names,
us_special_value_names,
us_short_weekday_names,
us_long_weekday_names,
'-',
boost::date_time::ymd_order_iso,
boost::date_time::month_as_short_string));
std::cout.imbue(usa_dates2);
std::cout << d1 << std::endl; // 2002-Oct-01
#else
std::cout << "Sorry, localization is not supported by this compiler/library"
<< std::endl;
#endif
return 0;
}
topDate Period Calculations
Calculates if a date is in an 'irregular' collection of periods using period calculation functions.
/*
This example demonstrates a simple use of periods for the calculation
of date information.
The example calculates if a given date is a weekend or holiday
given an exclusion set. That is, each weekend or holiday is
entered into the set as a time interval. Then if a given date
is contained within any of the intervals it is considered to
be within the exclusion set and hence is a offtime.
Output:
Number Excluded Periods: 5
20020202/20020203
20020209/20020210
20020212/20020212
20020216/20020217
In Exclusion Period: 20020216 --> 20020216/20020217
20020223/20020224
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <set>
#include <algorithm>
#include <iostream>
typedef std::set<boost::gregorian::date_period> date_period_set;
//Simple population of the exclusion set
date_period_set
generateExclusion()
{
using namespace boost::gregorian;
date_period periods_array[] =
{ date_period(date(2002,Feb,2), date(2002,Feb,4)),//weekend of 2nd-3rd
date_period(date(2002,Feb,9), date(2002,Feb,11)),
date_period(date(2002,Feb,16), date(2002,Feb,18)),
date_period(date(2002,Feb,23), date(2002,Feb,25)),
date_period(date(2002,Feb,12), date(2002,Feb,13))//a random holiday 2-12
};
const int num_periods = sizeof(periods_array)/sizeof(date_period);
date_period_set ps;
//insert the periods in the set
std::insert_iterator<date_period_set> itr(ps, ps.begin());
std::copy(periods_array, periods_array+num_periods, itr );
return ps;
}
int main()
{
using namespace boost::gregorian;
date_period_set ps = generateExclusion();
std::cout << "Number Excluded Periods: " << ps.size() << std::endl;
date d(2002,Feb,16);
date_period_set::const_iterator i = ps.begin();
//print the periods, check for containment
for (;i != ps.end(); i++) {
std::cout << to_iso_string(*i) << std::endl;
//if date is in exclusion period then print it
if (i->contains(d)) {
std::cout << "In Exclusion Period: "
<< to_iso_string(d) << " --> " << to_iso_string(*i)
<< std::endl;
}
}
return 0;
}
topPrint Holidays
This is an example of using functors to define a holiday schedule
/* Generate a set of dates using a collection of date generators
* Output looks like:
* Enter Year: 2002
* 2002-Jan-01 [Tue]
* 2002-Jan-21 [Mon]
* 2002-Feb-12 [Tue]
* 2002-Jul-04 [Thu]
* 2002-Sep-02 [Mon]
* 2002-Nov-28 [Thu]
* 2002-Dec-25 [Wed]
* Number Holidays: 7
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <algorithm>
#include <functional>
#include <vector>
#include <iostream>
#include <set>
void
print_date(boost::gregorian::date d)
{
using namespace boost::gregorian;
#if defined(BOOST_DATE_TIME_NO_LOCALE)
std::cout << to_simple_string(d) << " [" << d.day_of_week() << "]\n";
#else
std::cout << d << " [" << d.day_of_week() << "]\n";
#endif
}
int
main() {
std::cout << "Enter Year: ";
int year;
std::cin >> year;
using namespace boost::gregorian;
//define a collection of holidays fixed by month and day
std::vector<year_based_generator*> holidays;
holidays.push_back(new partial_date(1,Jan)); //Western New Year
holidays.push_back(new partial_date(4,Jul)); //US Independence Day
holidays.push_back(new partial_date(25, Dec));//Christmas day
//define a shorthand for the nth_day_of_the_week_in_month function object
typedef nth_day_of_the_week_in_month nth_dow;
//US labor day
holidays.push_back(new nth_dow(nth_dow::first, Monday, Sep));
//MLK Day
holidays.push_back(new nth_dow(nth_dow::third, Monday, Jan));
//Pres day
holidays.push_back(new nth_dow(nth_dow::second, Tuesday, Feb));
//Thanksgiving
holidays.push_back(new nth_dow(nth_dow::fourth, Thursday, Nov));
typedef std::set<date> date_set;
date_set all_holidays;
for(std::vector<year_based_generator*>::iterator it = holidays.begin();
it != holidays.end(); ++it)
{
all_holidays.insert((*it)->get_date(year));
}
//print the holidays to the screen
std::for_each(all_holidays.begin(), all_holidays.end(), print_date);
std::cout << "Number Holidays: " << all_holidays.size() << std::endl;
return 0;
}
topPrint Month
Simple utility to print out days of the month with the days of a month. Demontstrates date iteration (date_time::date_itr).
/* This example prints all the dates in a month. It demonstrates
* the use of iterators as well as functions of the gregorian_calendar
*
* Output:
* Enter Year: 2002
* Enter Month(1..12): 2
* 2002-Feb-01 [Fri]
* 2002-Feb-02 [Sat]
* 2002-Feb-03 [Sun]
* 2002-Feb-04 [Mon]
* 2002-Feb-05 [Tue]
* 2002-Feb-06 [Wed]
* 2002-Feb-07 [Thu]
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <iostream>
int
main()
{
std::cout << "Enter Year: ";
int year, month;
std::cin >> year;
std::cout << "Enter Month(1..12): ";
std::cin >> month;
using namespace boost::gregorian;
try {
//Use the calendar to get the last day of the month
int eom_day = gregorian_calendar::end_of_month_day(year,month);
date endOfMonth(year,month,eom_day);
//construct an iterator starting with firt day of the month
day_iterator ditr(date(year,month,1));
//loop thru the days and print each one
for (; ditr <= endOfMonth; ++ditr) {
#if defined(BOOST_DATE_TIME_NO_LOCALE)
std::cout << to_simple_string(*ditr) << " ["
#else
std::cout << *ditr << " ["
#endif
<< ditr->day_of_week() << "]"
<< std::endl;
}
}
catch(std::exception& e) {
std::cout << "Error bad date, check your entry: \n"
<< " Details: " << e.what() << std::endl;
}
return 0;
}
topMonth Adding
Adding a month to a day without the use of iterators.
/* Simple program that uses the gregorian calendar to progress by exactly
* one month, irregardless of how many days are in that month.
*
* This method can be used as an alternative to iterators
*/
#include "boost/date_time/gregorian/gregorian.hpp"
#include <iostream>
int
main()
{
using namespace boost::gregorian;
typedef boost::date_time::month_functor<date> add_month;
date d = day_clock::local_day();
add_month mf(1);
date d2 = d + mf.get_offset(d);
std::cout << "Today is: " << to_simple_string(d) << ".\n"
<< "One month from today will be: " << to_simple_string(d2)
<< std::endl;
return 0;
}
topTime Math
Various types of calculations with times and time durations.
/* Some simple examples of constructing and calculating with times
* Output:
* 2002-Feb-01 00:00:00 - 2002-Feb-01 05:04:02.001000000 = -5:04:02.001000000
*/
#include "boost/date_time/posix_time/posix_time.hpp"
#include <iostream>
int
main()
{
using namespace boost::posix_time;
using namespace boost::gregorian;
date d(2002,Feb,1); //an arbitrary date
//construct a time by adding up some durations durations
ptime t1(d, hours(5)+minutes(4)+seconds(2)+millisec(1));
//construct a new time by subtracting some times
ptime t2 = t1 - hours(5)- minutes(4)- seconds(2)- millisec(1);
//construct a duration by taking the difference between times
time_duration td = t2 - t1;
std::cout << to_simple_string(t2) << " - "
<< to_simple_string(t1) << " = "
<< to_simple_string(td) << std::endl;
return 0;
}
topPrint Hours
Demonstrate time iteration, clock retrieval, and simple calculation.
/* Print the remaining hours of the day
* Uses the clock to get the local time
* Use an iterator to iterate over the remaining hours
* Retrieve the date part from a time
*
* Expected Output something like:
*
* 2002-Mar-08 16:30:59
* 2002-Mar-08 17:30:59
* 2002-Mar-08 18:30:59
* 2002-Mar-08 19:30:59
* 2002-Mar-08 20:30:59
* 2002-Mar-08 21:30:59
* 2002-Mar-08 22:30:59
* 2002-Mar-08 23:30:59
* Time left till midnight: 07:29:01
*/
#include "boost/date_time/posix_time/posix_time.hpp"
#include <iostream>
int
main()
{
using namespace boost::posix_time;
using namespace boost::gregorian;
//get the current time from the clock -- one second resolution
ptime now = second_clock::local_time();
//Get the date part out of the time
date today = now.date();
date tommorrow = today + days(1);
ptime tommorrow_start(tommorrow); //midnight
//iterator adds by one hour
time_iterator titr(now,hours(1));
for (; titr < tommorrow_start; ++titr) {
std::cout << to_simple_string(*titr) << std::endl;
}
time_duration remaining = tommorrow_start - now;
std::cout << "Time left till midnight: "
<< to_simple_string(remaining) << std::endl;
return 0;
}
topLocal to UTC Conversion
Demonstrate utc to local and local to utc calculations including dst.
/* Demonstrate conversions between a local time and utc
* Output:
*
* UTC <--> New York while DST is NOT active (5 hours)
* 2001-Dec-31 19:00:00 in New York is 2002-Jan-01 00:00:00 UTC time
* 2002-Jan-01 00:00:00 UTC is 2001-Dec-31 19:00:00 New York time
*
* UTC <--> New York while DST is active (4 hours)
* 2002-May-31 20:00:00 in New York is 2002-Jun-01 00:00:00 UTC time
* 2002-Jun-01 00:00:00 UTC is 2002-May-31 20:00:00 New York time
*
* UTC <--> Arizona (7 hours)
* 2002-May-31 17:00:00 in Arizona is 2002-Jun-01 00:00:00 UTC time
*/
#include "boost/date_time/posix_time/posix_time.hpp"
#include "boost/date_time/local_time_adjustor.hpp"
#include "boost/date_time/c_local_time_adjustor.hpp"
#include <iostream>
int
main()
{
using namespace boost::posix_time;
using namespace boost::gregorian;
//This local adjustor depends on the machine TZ settings-- highly dangerous!
typedef boost::date_time::c_local_adjustor<ptime> local_adj;
ptime t10(date(2002,Jan,1), hours(7));
ptime t11 = local_adj::utc_to_local(t10);
std::cout << "UTC <--> Zone base on TZ setting" << std::endl;
std::cout << to_simple_string(t11) << " in your TZ is "
<< to_simple_string(t10) << " UTC time "
<< std::endl;
time_duration td = t11 - t10;
std::cout << "A difference of: "
<< to_simple_string(td) << std::endl;
//eastern timezone is utc-5
typedef boost::date_time::local_adjustor<ptime, -5, us_dst> us_eastern;
ptime t1(date(2001,Dec,31), hours(19)); //5 hours b/f midnight NY time
std::cout << "\nUTC <--> New York while DST is NOT active (5 hours)"
<< std::endl;
ptime t2 = us_eastern::local_to_utc(t1);
std::cout << to_simple_string(t1) << " in New York is "
<< to_simple_string(t2) << " UTC time "
<< std::endl;
ptime t3 = us_eastern::utc_to_local(t2);//back should be the same
std::cout << to_simple_string(t2) << " UTC is "
<< to_simple_string(t3) << " New York time "
<< "\n\n";
ptime t4(date(2002,May,31), hours(20)); //4 hours b/f midnight NY time
std::cout << "UTC <--> New York while DST is active (4 hours)" << std::endl;
ptime t5 = us_eastern::local_to_utc(t4);
std::cout << to_simple_string(t4) << " in New York is "
<< to_simple_string(t5) << " UTC time "
<< std::endl;
ptime t6 = us_eastern::utc_to_local(t5);//back should be the same
std::cout << to_simple_string(t5) << " UTC is "
<< to_simple_string(t6) << " New York time "
<< "\n" << std::endl;
//Arizona timezone is utc-7 with no dst
typedef boost::date_time::local_adjustor<ptime, -7, no_dst> us_arizona;
ptime t7(date(2002,May,31), hours(17));
std::cout << "UTC <--> Arizona (7 hours)" << std::endl;
ptime t8 = us_arizona::local_to_utc(t7);
std::cout << to_simple_string(t7) << " in Arizona is "
<< to_simple_string(t8) << " UTC time "
<< std::endl;
return 0;
}
topTime Periods
Demonstrate some simple uses of time periods.
/* Some simple examples of constructing and calculating with times
* Returns:
* [2002-Feb-01 00:00:00/2002-Feb-01 23:59:59.999999999] contains 2002-Feb-01 03:00:05
* [2002-Feb-01 00:00:00/2002-Feb-01 23:59:59.999999999] intersected with
* [2002-Feb-01 00:00:00/2002-Feb-01 03:00:04.999999999] is
* [2002-Feb-01 00:00:00/2002-Feb-01 03:00:04.999999999]
*/
#include "boost/date_time/posix_time/posix_time.hpp"
#include <iostream>
using namespace boost::posix_time;
using namespace boost::gregorian;
//Create a simple period class to contain all the times in a day
class day_period : public time_period
{
public:
day_period(date d) : time_period(ptime(d),//midnight
ptime(d,hours(24)))
{}
};
int
main()
{
date d(2002,Feb,1); //an arbitrary date
//a period that represents a day
day_period dp(d);
ptime t(d, hours(3)+seconds(5)); //an arbitray time on that day
if (dp.contains(t)) {
std::cout << to_simple_string(dp) << " contains "
<< to_simple_string(t) << std::endl;
}
//a period that represents part of the day
time_period part_of_day(ptime(d, hours(0)), t);
//intersect the 2 periods and print the results
if (part_of_day.intersects(dp)) {
time_period result = part_of_day.intersection(dp);
std::cout << to_simple_string(dp) << " intersected with\n"
<< to_simple_string(part_of_day) << " is \n"
<< to_simple_string(result) << std::endl;
}
return 0;
}
topLibrary Reference
The following is a detailed reference of the date_time library. A click on any of the reference links will take you to a list of the header files found in that section. Following one of those links will take you to a list of the items declared in that header file. Further sublinks take you to detailed descriptions of each individual item.
Date Time ReferenceHeader <<ulink url="../../boost/date_time/adjust_functors.hpp">boost/date_time/adjust_functors.hpp</ulink>>namespace boost {
namespace date_time {
template<typename date_type> class day_functor;
template<typename date_type> class month_functor;
template<typename date_type> class week_functor;
template<typename date_type> class year_functor;
}
}Class template day_functor3boost::date_time::day_functorFunctor to iterate a fixed number of days. template<typename date_type>
class day_functor {
public:
// typestypedef date_type::duration_type duration_type;
// construct/copy/destruct
day_functor(int);
// public member functionsduration_type get_offset(const date_type &) const;
duration_type get_neg_offset(const date_type &) const;
};Description<anchor id="day_functorconstruct-copy-destruct"/><computeroutput>day_functor</computeroutput> construct/copy/destructday_functor(int f);<anchor id="id374751-bb"/><computeroutput>day_functor</computeroutput> public member functionsduration_typeget_offset(const date_type & d) const;duration_typeget_neg_offset(const date_type & d) const;Class template month_functor3boost::date_time::month_functorProvides calculation to find next nth month given a date. template<typename date_type>
class month_functor {
public:
// typestypedef date_type::duration_type duration_type;
typedef date_type::calendar_type cal_type;
typedef cal_type::ymd_type ymd_type;
typedef cal_type::day_type day_type;
// construct/copy/destruct
month_functor(int);
// public member functionsduration_type get_offset(const date_type &) const;
duration_type get_neg_offset(const date_type &) const;
};DescriptionThis adjustment function provides the logic for 'month-based' advancement on a ymd based calendar. The policy it uses to handle the non existant end of month days is to back up to the last day of the month. Also, if the starting date is the last day of a month, this functor will attempt to adjust to the end of the month. <anchor id="month_functorconstruct-copy-destruct"/><computeroutput>month_functor</computeroutput> construct/copy/destructmonth_functor(int f);<anchor id="id349946-bb"/><computeroutput>month_functor</computeroutput> public member functionsduration_typeget_offset(const date_type & d) const;duration_typeget_neg_offset(const date_type & d) const;Returns a negative duration_type. Class template week_functor3boost::date_time::week_functorFunctor to iterate a over weeks. template<typename date_type>
class week_functor {
public:
// typestypedef date_type::duration_type duration_type;
typedef date_type::calendar_type calendar_type;
// construct/copy/destruct
week_functor(int);
// public member functionsduration_type get_offset(const date_type &) const;
duration_type get_neg_offset(const date_type &) const;
};Description<anchor id="week_functorconstruct-copy-destruct"/><computeroutput>week_functor</computeroutput> construct/copy/destructweek_functor(int f);<anchor id="id435416-bb"/><computeroutput>week_functor</computeroutput> public member functionsduration_typeget_offset(const date_type & d) const;duration_typeget_neg_offset(const date_type & d) const;Class template year_functor3boost::date_time::year_functorFunctor to iterate by a year adjusting for leap years. template<typename date_type>
class year_functor {
public:
// typestypedef date_type::duration_type duration_type;
// construct/copy/destruct
year_functor(int);
// public member functionsduration_type get_offset(const date_type &) const;
duration_type get_neg_offset(const date_type &) const;
};Description<anchor id="year_functorconstruct-copy-destruct"/><computeroutput>year_functor</computeroutput> construct/copy/destructyear_functor(int f);<anchor id="id312559-bb"/><computeroutput>year_functor</computeroutput> public member functionsduration_typeget_offset(const date_type & d) const;duration_typeget_neg_offset(const date_type & d) const;Header <<ulink url="../../boost/date_time/c_local_time_adjustor.hpp">boost/date_time/c_local_time_adjustor.hpp</ulink>>Time adjustment calculations based on machinenamespace boost {
namespace date_time {
template<typename time_type> class c_local_adjustor;
}
}Class template c_local_adjustor3boost::date_time::c_local_adjustorAdjust to / from utc using the C API. template<typename time_type>
class c_local_adjustor {
public:
// typestypedef time_type::time_duration_type time_duration_type;
typedef time_type::date_type date_type;
typedef date_type::duration_type date_duration_type;
// public static functionstime_type utc_to_local(const time_type &) ;
};DescriptionWarning!!! This class assumes that timezone settings of the machine are correct. This can be a very dangerous assumption. <anchor id="id317142-bb"/><computeroutput>c_local_adjustor</computeroutput> public static functionstime_typeutc_to_local(const time_type & t) ;Convert a utc time to local time. Header <<ulink url="../../boost/date_time/c_time.hpp">boost/date_time/c_time.hpp</ulink>>Provide workarounds related to the ctime headernamespace std {
}Header <<ulink url="../../boost/date_time/compiler_config.hpp">boost/date_time/compiler_config.hpp</ulink>>namespace std {
}Header <<ulink url="../../boost/date_time/constrained_value.hpp">boost/date_time/constrained_value.hpp</ulink>>namespace boost {
namespace CV {
template<typename value_policies> class constrained_value;
template<typename rep_type, rep_type min_value, rep_type max_value,
typename exception_type>
class simple_exception_policy;
// Represent a min or max violation type. enumviolation_enum { min_violation, max_violation };
}
}Class template constrained_value3boost::CV::constrained_valueA template to specify a constrained basic value type. template<typename value_policies>
class constrained_value {
public:
// typestypedef value_policies::value_type value_type;
// construct/copy/destruct
constrained_value(value_type);
constrained_value& operator=(value_type);
// public member functionsoperator value_type() const;
// public static functionsvalue_type max BOOST_PREVENT_MACRO_SUBSTITUTION() ;
value_type min BOOST_PREVENT_MACRO_SUBSTITUTION() ;
// private member functionsvoid assign(value_type) ;
};DescriptionThis template provides a quick way to generate an integer type with a constrained range. The type provides for the ability to specify the min, max, and and error handling policy.value policies A class that provides the range limits via the min and max functions as well as a function on_error that determines how errors are handled. A common strategy would be to assert or throw and exception. The on_error is passed both the current value and the new value that is in error. <anchor id="constrained_valueconstruct-copy-destruct"/><computeroutput>constrained_value</computeroutput> construct/copy/destructconstrained_value(value_type value);constrained_value& operator=(value_type v);<anchor id="id405391-bb"/><computeroutput>constrained_value</computeroutput> public member functionsoperator value_type() const;Coerce into the representation type. <anchor id="id315083-bb"/><computeroutput>constrained_value</computeroutput> public static functionsvalue_type maxBOOST_PREVENT_MACRO_SUBSTITUTION() ;Return the max allowed value (traits method). value_type minBOOST_PREVENT_MACRO_SUBSTITUTION() ;Return the min allowed value (traits method). <anchor id="id336013-bb"/><computeroutput>constrained_value</computeroutput> private member functionsvoidassign(value_type value) ;Class template simple_exception_policy3boost::CV::simple_exception_policyTemplate to shortcut the constrained_value policy creation process. template<typename rep_type, rep_type min_value, rep_type max_value,
typename exception_type>
class simple_exception_policy {
public:
// typestypedef rep_type value_type;
// public static functionsrep_type min BOOST_PREVENT_MACRO_SUBSTITUTION() ;
rep_type max BOOST_PREVENT_MACRO_SUBSTITUTION() ;
void on_error(rep_type, rep_type, violation_enum) ;
};Description<anchor id="id353157-bb"/><computeroutput>simple_exception_policy</computeroutput> public static functionsrep_type minBOOST_PREVENT_MACRO_SUBSTITUTION() ;rep_type maxBOOST_PREVENT_MACRO_SUBSTITUTION() ;voidon_error(rep_type , rep_type , violation_enum ) ;Header <<ulink url="../../boost/date_time/date.hpp">boost/date_time/date.hpp</ulink>>namespace boost {
namespace date_time {
template<typename T, typename calendar, typename duration_type_> class date;
}
}Class template date3boost::date_time::dateRepresentation of timepoint at the one day level resolution. template<typename T, typename calendar, typename duration_type_>
class date {
public:
// typestypedef T date_type;
typedef calendar calendar_type;
typedef calendar::date_traits_type traits_type;
typedef duration_type_ duration_type;
typedef calendar::year_type year_type;
typedef calendar::month_type month_type;
typedef calendar::day_type day_type;
typedef calendar::ymd_type ymd_type;
typedef calendar::date_rep_type date_rep_type;
typedef calendar::date_int_type date_int_type;
typedef calendar::day_of_week_type day_of_week_type;
// construct/copy/destruct
date(year_type, month_type, day_type);
date(const ymd_type &);
date(date_int_type);
date(date_rep_type);
// public member functionsyear_type year() const;
month_type month() const;
day_type day() const;
day_of_week_type day_of_week() const;
ymd_type year_month_day() const;
booloperator<(const date_type &) const;
booloperator==(const date_type &) const;
bool is_special() const;
bool is_not_a_date() const;
bool is_infinity() const;
bool is_pos_infinity() const;
bool is_neg_infinity() const;
special_values as_special() const;
duration_typeoperator-(const date_type &) const;
date_typeoperator-(const duration_type &) const;
date_typeoperator-=(const duration_type &) ;
date_rep_type day_count() const;
date_typeoperator+(const duration_type &) const;
date_typeoperator+=(const duration_type &) ;
// protected member functions
};DescriptionThe date template represents an interface shell for a date class that is based on a year-month-day system such as the gregorian or iso systems. It provides basic operations to enable calculation and comparisons.TheoryThis date representation fundamentally departs from the C tm struct approach. The goal for this type is to provide efficient date operations (add, subtract) and storage (minimize space to represent) in a concrete class. Thus, the date uses a count internally to represent a particular date. The calendar parameter defines the policies for converting the the year-month-day and internal counted form here. Applications that need to perform heavy formatting of the same date repeatedly will perform better by using the year-month-day representation.Internally the date uses a day number to represent the date. This is a monotonic time representation. This representation allows for fast comparison as well as simplifying the creation of writing numeric operations. Essentially, the internal day number is like adjusted julian day. The adjustment is determined by the Epoch date which is represented as day 1 of the calendar. Day 0 is reserved for negative infinity so that any actual date is automatically greater than negative infinity. When a date is constructed from a date or formatted for output, the appropriate conversions are applied to create the year, month, day representations. <anchor id="boost.date_time.dateconstruct-copy-destruct"/><computeroutput>date</computeroutput> construct/copy/destructdate(year_type y, month_type m, day_type d);date(const ymd_type & ymd);date(date_int_type days);This is a private constructor which allows for the creation of new dates. It is not exposed to users since that would require class users to understand the inner workings of the date class. date(date_rep_type days);<anchor id="id397241-bb"/><computeroutput>date</computeroutput> public member functionsyear_typeyear() const;month_typemonth() const;day_typeday() const;day_of_week_typeday_of_week() const;ymd_typeyear_month_day() const;booloperator<(const date_type & rhs) const;booloperator==(const date_type & rhs) const;boolis_special() const;check to see if date is a special value boolis_not_a_date() const;check to see if date is not a value boolis_infinity() const;check to see if date is one of the infinity values boolis_pos_infinity() const;check to see if date is greater than all possible dates boolis_neg_infinity() const;check to see if date is greater than all possible dates special_valuesas_special() const;return as a special value or a not_special if a normal date duration_typeoperator-(const date_type & d) const;date_typeoperator-(const duration_type & dd) const;date_typeoperator-=(const duration_type & dd) ;date_rep_typeday_count() const;date_typeoperator+(const duration_type & dd) const;date_typeoperator+=(const duration_type & dd) ;<anchor id="id401946-bb"/><computeroutput>date</computeroutput> protected member functionsHeader <<ulink url="../../boost/date_time/date_clock_device.hpp">boost/date_time/date_clock_device.hpp</ulink>>namespace boost {
namespace date_time {
template<typename date_type> class day_clock;
}
}Class template day_clock3boost::date_time::day_clockA clock providing day level services based on C time_t capabilities. template<typename date_type>
class day_clock {
public:
// typestypedef date_type::ymd_type ymd_type;
// public static functionsdate_type local_day() ;
date_type::ymd_type local_day_ymd() ;
date_type::ymd_type universal_day_ymd() ;
date_type universal_day() ;
// private static functions::std::tm * get_local_time() ;
::std::tm * get_universal_time() ;
};DescriptionThis clock uses Posix interfaces as its implementation and hence uses the timezone settings of the operating system. Incorrect user settings will result in incorrect results for the calls to local_day. <anchor id="id423222-bb"/><computeroutput>day_clock</computeroutput> public static functionsdate_typelocal_day() ;Get the local day as a date type. date_type::ymd_typelocal_day_ymd() ;Get the local day as a ymd_type. date_type::ymd_typeuniversal_day_ymd() ;Get the current day in universal date as a ymd_type. date_typeuniversal_day() ;Get the UTC day as a date type. <anchor id="id329464-bb"/><computeroutput>day_clock</computeroutput> private static functions::std::tm *get_local_time() ;::std::tm *get_universal_time() ;Header <<ulink url="../../boost/date_time/date_defs.hpp">boost/date_time/date_defs.hpp</ulink>>namespace boost {
namespace date_time {
// An enumeration of weekday names. enumweekdays { Sunday, Monday, Tuesday, Wednesday, Thursday, Friday,
Saturday };
// Simple enum to allow for nice programming with Jan, Feb, etc. enummonths_of_year { Jan = 1, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct,
Nov, Dec, NotAMonth, NumMonths };
}
}Header <<ulink url="../../boost/date_time/date_duration.hpp">boost/date_time/date_duration.hpp</ulink>>namespace boost {
namespace date_time {
template<typename duration_rep_traits> class date_duration;
struct duration_traits_long;
struct duration_traits_adapted;
}
}Class template date_duration3boost::date_time::date_durationDuration type with date level resolution. template<typename duration_rep_traits>
class date_duration {
public:
// typestypedef duration_rep_traits::int_type duration_rep_type;
typedef duration_rep_traits::impl_type duration_rep;
// construct/copy/destruct
date_duration(duration_rep);
date_duration(special_values);
date_duration(const date_duration< duration_rep_traits > &);
// public member functionsduration_rep get_rep() const;
bool is_special() const;
duration_rep_type days() const;
booloperator==(const date_duration &) const;
booloperator<(const date_duration &) const;
date_durationoperator-=(const date_duration &) ;
date_durationoperator+=(const date_duration &) ;
date_durationoperator-() const;
date_duration< duration_rep_traits >operator/=(int) ;
date_duration< duration_rep_traits >operator/(int) ;
bool is_negative() const;
// public static functionsdate_duration unit() ;
};Description<anchor id="date_durationconstruct-copy-destruct"/><computeroutput>date_duration</computeroutput> construct/copy/destructdate_duration(duration_rep day_count);Construct from a day count. date_duration(special_values sv);construct from special_values - only works when instantiated with duration_traits_adapted date_duration(const date_duration< duration_rep_traits > & other);Construct from another date_duration (Copy Constructor). <anchor id="id423776-bb"/><computeroutput>date_duration</computeroutput> public member functionsduration_repget_rep() const;returns days_ as it's instantiated type - used for streaming boolis_special() const;duration_rep_typedays() const;returns days as value, not object. booloperator==(const date_duration & rhs) const;Equality. booloperator<(const date_duration & rhs) const;Less. date_durationoperator-=(const date_duration & rhs) ;Subtract another duration -- result is signed. date_durationoperator+=(const date_duration & rhs) ;Add a duration -- result is signed. date_durationoperator-() const;unary- Allows for dd = -date_duration(2); -> dd == -2 date_duration< duration_rep_traits >operator/=(int divisor) ;Division operations on a duration with an integer. date_duration< duration_rep_traits >operator/(int divisor) ;boolis_negative() const;return sign information <anchor id="id400391-bb"/><computeroutput>date_duration</computeroutput> public static functionsdate_durationunit() ;Returns the smallest duration -- used by to calculate 'end'. Struct duration_traits_long3boost::date_time::duration_traits_longstruct duration_traits_long {
// typestypedeflong int_type;
typedeflong impl_type;
// public static functionsint_type as_number(impl_type) ;
};DescriptionStruct for instantiating date_duration with NO special values functionality. Allows for transparent implementation of either date_duration<long> or date_duration<int_adapter<long> > <anchor id="id413989-bb"/><computeroutput>duration_traits_long</computeroutput> public static functionsint_typeas_number(impl_type i) ;Struct duration_traits_adapted3boost::date_time::duration_traits_adaptedstruct duration_traits_adapted {
// typestypedeflong int_type;
typedef boost::date_time::int_adapter< long > impl_type;
// public static functionsint_type as_number(impl_type) ;
};DescriptionStruct for instantiating date_duration WITH special values functionality. Allows for transparent implementation of either date_duration<long> or date_duration<int_adapter<long> > <anchor id="id360428-bb"/><computeroutput>duration_traits_adapted</computeroutput> public static functionsint_typeas_number(impl_type i) ;Header <<ulink url="../../boost/date_time/date_duration_types.hpp">boost/date_time/date_duration_types.hpp</ulink>>namespace boost {
namespace date_time {
template<typename duration_config> class weeks_duration;
template<typename base_config> class months_duration;
template<typename base_config> class years_duration;
}
}Class template weeks_duration3boost::date_time::weeks_durationAdditional duration type that represents a number of n*7 days. template<typename duration_config>
class weeks_duration
: : public boost::date_time::date_duration< duration_config >
{
public:
// construct/copy/destruct
weeks_duration(typename duration_config::impl_type);
weeks_duration(special_values);
// public member functions
};Description<anchor id="weeks_durationconstruct-copy-destruct"/><computeroutput>weeks_duration</computeroutput> construct/copy/destructweeks_duration(typename duration_config::impl_type w);weeks_duration(special_values sv);<anchor id="id356004-bb"/><computeroutput>weeks_duration</computeroutput> public member functionsClass template months_duration3boost::date_time::months_durationadditional duration type that represents a logical month template<typename base_config>
class months_duration {
public:
// construct/copy/destruct
months_duration(int_rep);
months_duration(special_values);
// public member functionsint_rep number_of_months() const;
duration_type get_neg_offset(const date_type &) const;
duration_type get_offset(const date_type &) const;
booloperator==(const months_type &) const;
booloperator!=(const months_type &) const;
months_typeoperator+(const months_type &) const;
months_type &operator+=(const months_type &) ;
months_typeoperator-(const months_type &) const;
months_type &operator-=(const months_type &) ;
months_typeoperator *(const int_type) const;
months_type &operator *=(const int_type) ;
months_typeoperator/(const int_type) const;
months_type &operator/=(const int_type) ;
months_typeoperator+(const years_type &) const;
months_type &operator+=(const years_type &) ;
months_typeoperator-(const years_type &) const;
months_type &operator-=(const years_type &) ;
};DescriptionA logical month enables things like: "date(2002,Mar,2) + months(2) -> 2002-May2". If the date is a last day-of-the-month, the result will also be a last-day-of-the-month. <anchor id="months_durationconstruct-copy-destruct"/><computeroutput>months_duration</computeroutput> construct/copy/destructmonths_duration(int_rep num);months_duration(special_values sv);<anchor id="id398297-bb"/><computeroutput>months_duration</computeroutput> public member functionsint_repnumber_of_months() const;duration_typeget_neg_offset(const date_type & d) const;returns a negative duration duration_typeget_offset(const date_type & d) const;booloperator==(const months_type & rhs) const;booloperator!=(const months_type & rhs) const;months_typeoperator+(const months_type & rhs) const;months_type &operator+=(const months_type & rhs) ;months_typeoperator-(const months_type & rhs) const;months_type &operator-=(const months_type & rhs) ;months_typeoperator *(const int_type rhs) const;months_type &operator *=(const int_type rhs) ;months_typeoperator/(const int_type rhs) const;months_type &operator/=(const int_type rhs) ;months_typeoperator+(const years_type & y) const;months_type &operator+=(const years_type & y) ;months_typeoperator-(const years_type & y) const;months_type &operator-=(const years_type & y) ;Class template years_duration3boost::date_time::years_durationadditional duration type that represents a logical year template<typename base_config>
class years_duration {
public:
// construct/copy/destruct
years_duration(int_rep);
years_duration(special_values);
// public member functionsint_rep number_of_years() const;
duration_type get_neg_offset(const date_type &) const;
duration_type get_offset(const date_type &) const;
booloperator==(const years_type &) const;
booloperator!=(const years_type &) const;
years_typeoperator+(const years_type &) const;
years_type &operator+=(const years_type &) ;
years_typeoperator-(const years_type &) const;
years_type &operator-=(const years_type &) ;
years_typeoperator *(const int_type) const;
years_type &operator *=(const int_type) ;
years_typeoperator/(const int_type) const;
years_type &operator/=(const int_type) ;
months_typeoperator+(const months_type &) const;
months_typeoperator-(const months_type &) const;
};DescriptionA logical year enables things like: "date(2002,Mar,2) + years(2) -> 2004-Mar-2". If the date is a last day-of-the-month, the result will also be a last-day-of-the-month (ie date(2001-Feb-28) + years(3) -> 2004-Feb-29). <anchor id="years_durationconstruct-copy-destruct"/><computeroutput>years_duration</computeroutput> construct/copy/destructyears_duration(int_rep num);years_duration(special_values sv);<anchor id="id385605-bb"/><computeroutput>years_duration</computeroutput> public member functionsint_repnumber_of_years() const;duration_typeget_neg_offset(const date_type & d) const;returns a negative duration duration_typeget_offset(const date_type & d) const;booloperator==(const years_type & rhs) const;booloperator!=(const years_type & rhs) const;years_typeoperator+(const years_type & rhs) const;years_type &operator+=(const years_type & rhs) ;years_typeoperator-(const years_type & rhs) const;years_type &operator-=(const years_type & rhs) ;years_typeoperator *(const int_type rhs) const;years_type &operator *=(const int_type rhs) ;years_typeoperator/(const int_type rhs) const;years_type &operator/=(const int_type rhs) ;months_typeoperator+(const months_type & m) const;months_typeoperator-(const months_type & m) const;Header <<ulink url="../../boost/date_time/date_format_simple.hpp">boost/date_time/date_format_simple.hpp</ulink>>namespace boost {
namespace date_time {
template<typename charT> class simple_format;
template<> class simple_format<wchar_t>;
}
}Class template simple_format3boost::date_time::simple_formatClass to provide simple basic formatting rules. template<typename charT>
class simple_format {
public:
// public static functionsconst charT * not_a_date() ;
const charT * pos_infinity() ;
const charT * neg_infinity() ;
month_format_spec month_format() ;
ymd_order_spec date_order() ;
bool has_date_sep_chars() ;
charT year_sep_char() ;
charT month_sep_char() ;
charT day_sep_char() ;
charT hour_sep_char() ;
charT minute_sep_char() ;
charT second_sep_char() ;
};Description<anchor id="id393016-bb"/><computeroutput>simple_format</computeroutput> public static functionsconst charT *not_a_date() ;String used printed is date is invalid. const charT *pos_infinity() ;String used to for positive infinity value. const charT *neg_infinity() ;String used to for positive infinity value. month_format_specmonth_format() ;Describe month format. ymd_order_specdate_order() ;boolhas_date_sep_chars() ;This format uses '-' to separate date elements. charTyear_sep_char() ;Char to sep? charTmonth_sep_char() ;char between year-month charTday_sep_char() ;Char to separate month-day. charThour_sep_char() ;char between date-hours charTminute_sep_char() ;char between hour and minute charTsecond_sep_char() ;char for second SpecializationsClass simple_format<wchar_t>Class simple_format<wchar_t>3boost::date_time::simple_format<wchar_t>Specialization of formmating rules for wchar_t. class simple_format<wchar_t> {
public:
// public static functionsconstwchar_t * not_a_date() ;
constwchar_t * pos_infinity() ;
constwchar_t * neg_infinity() ;
month_format_spec month_format() ;
ymd_order_spec date_order() ;
bool has_date_sep_chars() ;
wchar_t year_sep_char() ;
wchar_t month_sep_char() ;
wchar_t day_sep_char() ;
wchar_t hour_sep_char() ;
wchar_t minute_sep_char() ;
wchar_t second_sep_char() ;
};Description<anchor id="id417252-bb"/><computeroutput>simple_format</computeroutput> public static functionsconstwchar_t *not_a_date() ;String used printed is date is invalid. constwchar_t *pos_infinity() ;String used to for positive infinity value. constwchar_t *neg_infinity() ;String used to for positive infinity value. month_format_specmonth_format() ;Describe month format. ymd_order_specdate_order() ;boolhas_date_sep_chars() ;This format uses '-' to separate date elements. wchar_tyear_sep_char() ;Char to sep? wchar_tmonth_sep_char() ;char between year-month wchar_tday_sep_char() ;Char to separate month-day. wchar_thour_sep_char() ;char between date-hours wchar_tminute_sep_char() ;char between hour and minute wchar_tsecond_sep_char() ;char for second Header <<ulink url="../../boost/date_time/date_formatting.hpp">boost/date_time/date_formatting.hpp</ulink>>namespace boost {
namespace date_time {
template<typename month_type, typename format_type, typename charT = char>
class month_formatter;
template<typename ymd_type, typename format_type, typename charT = char>
class ymd_formatter;
template<typename date_type, typename format_type, typename charT = char>
class date_formatter;
}
}Class template month_formatter3boost::date_time::month_formatterFormats a month as as string into an ostream. template<typename month_type, typename format_type, typename charT = char>
class month_formatter {
public:
// public static functionsstd::basic_ostream< charT > &
format_month(const month_type &, std::basic_ostream< charT > &) ;
std::ostream & format_month(const month_type &, std::ostream &) ;
};Description<anchor id="id421978-bb"/><computeroutput>month_formatter</computeroutput> public static functionsstd::basic_ostream< charT > &format_month(const month_type & month, std::basic_ostream< charT > & os) ;Formats a month as as string into an ostream. This function demands that month_type provide functions for converting to short and long strings if that capability is used. std::ostream &format_month(const month_type & month, std::ostream & os) ;Formats a month as as string into an ostream. This function demands that month_type provide functions for converting to short and long strings if that capability is used. Class template ymd_formatter3boost::date_time::ymd_formatterConvert ymd to a standard string formatting policies. template<typename ymd_type, typename format_type, typename charT = char>
class ymd_formatter {
public:
// public static functionsstd::basic_string< charT > ymd_to_string(ymd_type) ;
std::string ymd_to_string(ymd_type) ;
};Description<anchor id="id403200-bb"/><computeroutput>ymd_formatter</computeroutput> public static functionsstd::basic_string< charT >ymd_to_string(ymd_type ymd) ;Convert ymd to a standard string formatting policies. This is standard code for handling date formatting with year-month-day based date information. This function uses the format_type to control whether the string will contain separator characters, and if so what the character will be. In addtion, it can format the month as either an integer or a string as controled by the formatting policy std::stringymd_to_string(ymd_type ymd) ;Convert ymd to a standard string formatting policies. This is standard code for handling date formatting with year-month-day based date information. This function uses the format_type to control whether the string will contain separator characters, and if so what the character will be. In addtion, it can format the month as either an integer or a string as controled by the formatting policy Class template date_formatter3boost::date_time::date_formatterConvert a date to string using format policies. template<typename date_type, typename format_type, typename charT = char>
class date_formatter {
public:
// typestypedef std::basic_string< charT > string_type;
// public static functionsstring_type date_to_string(date_type) ;
std::string date_to_string(date_type) ;
};Description<anchor id="id408662-bb"/><computeroutput>date_formatter</computeroutput> public static functionsstring_typedate_to_string(date_type d) ;Convert to a date to standard string using format policies. std::stringdate_to_string(date_type d) ;Convert to a date to standard string using format policies. Header <<ulink url="../../boost/date_time/date_formatting_limited.hpp">boost/date_time/date_formatting_limited.hpp</ulink>>namespace boost {
namespace date_time {
}
}Header <<ulink url="../../boost/date_time/date_formatting_locales.hpp">boost/date_time/date_formatting_locales.hpp</ulink>>namespace boost {
namespace date_time {
template<typename facet_type, typename charT = char>
class ostream_month_formatter;
template<typename weekday_type, typename facet_type,
typename charT = char>
class ostream_weekday_formatter;
template<typename ymd_type, typename facet_type, typename charT = char>
class ostream_ymd_formatter;
template<typename date_type, typename facet_type, typename charT = char>
class ostream_date_formatter;
}
}Class template ostream_month_formatter3boost::date_time::ostream_month_formatterFormats a month as as string into an ostream. template<typename facet_type, typename charT = char>
class ostream_month_formatter {
public:
// typestypedef facet_type::month_type month_type;
typedef std::basic_ostream< charT > ostream_type;
// public static functionsvoid format_month(const month_type &, ostream_type &, const facet_type &) ;
};Description<anchor id="id419858-bb"/><computeroutput>ostream_month_formatter</computeroutput> public static functionsvoidformat_month(const month_type & month, ostream_type & os,
const facet_type & f) ;Formats a month as as string into an output iterator. Class template ostream_weekday_formatter3boost::date_time::ostream_weekday_formatterFormats a weekday. template<typename weekday_type, typename facet_type, typename charT = char>
class ostream_weekday_formatter {
public:
// typestypedef facet_type::month_type month_type;
typedef std::basic_ostream< charT > ostream_type;
// public static functionsvoid format_weekday(const weekday_type &, ostream_type &,
const facet_type &, bool) ;
};Description<anchor id="id430414-bb"/><computeroutput>ostream_weekday_formatter</computeroutput> public static functionsvoidformat_weekday(const weekday_type & wd, ostream_type & os,
const facet_type & f, bool as_long_string) ;Formats a month as as string into an output iterator. Class template ostream_ymd_formatter3boost::date_time::ostream_ymd_formatterConvert ymd to a standard string formatting policies. template<typename ymd_type, typename facet_type, typename charT = char>
class ostream_ymd_formatter {
public:
// typestypedef ymd_type::month_type month_type;
typedef ostream_month_formatter< facet_type, charT > month_formatter_type;
typedef std::basic_ostream< charT > ostream_type;
typedef std::basic_string< charT > foo_type;
// public static functionsvoid ymd_put(ymd_type, ostream_type &, const facet_type &) ;
};Description<anchor id="id401924-bb"/><computeroutput>ostream_ymd_formatter</computeroutput> public static functionsvoidymd_put(ymd_type ymd, ostream_type & os, const facet_type & f) ;Convert ymd to a standard string formatting policies. This is standard code for handling date formatting with year-month-day based date information. This function uses the format_type to control whether the string will contain separator characters, and if so what the character will be. In addtion, it can format the month as either an integer or a string as controled by the formatting policy Class template ostream_date_formatter3boost::date_time::ostream_date_formatterConvert a date to string using format policies. template<typename date_type, typename facet_type, typename charT = char>
class ostream_date_formatter {
public:
// typestypedef std::basic_ostream< charT > ostream_type;
typedef date_type::ymd_type ymd_type;
// public static functionsvoid date_put(const date_type &, ostream_type &, const facet_type &) ;
void date_put(const date_type &, ostream_type &) ;
};Description<anchor id="id333524-bb"/><computeroutput>ostream_date_formatter</computeroutput> public static functionsvoiddate_put(const date_type & d, ostream_type & os, const facet_type & f) ;Put date into an ostream. voiddate_put(const date_type & d, ostream_type & os) ;Put date into an ostream. Header <<ulink url="../../boost/date_time/date_generators.hpp">boost/date_time/date_generators.hpp</ulink>>Definition and implementation of date algorithm templatesnamespace boost {
namespace date_time {
template<typename date_type> class year_based_generator;
template<typename date_type> class partial_date;
template<typename date_type> class nth_kday_of_month;
template<typename date_type> class first_kday_of_month;
template<typename date_type> class last_kday_of_month;
template<typename date_type> class first_kday_after;
template<typename date_type> class first_kday_before;
// Returns nth arg as string. 1 -> "first", 2 -> "second", max is 5. BOOST_DATE_TIME_DECL constchar *nth_as_str(int n);
template<typename date_type, typename weekday_type>
date_type::duration_type
days_until_weekday(const date_type &, const weekday_type &);
template<typename date_type, typename weekday_type>
date_type::duration_type
days_before_weekday(const date_type &, const weekday_type &);
template<typename date_type, typename weekday_type>
date_type next_weekday(const date_type &, const weekday_type &);
template<typename date_type, typename weekday_type>
date_type previous_weekday(const date_type &, const weekday_type &);
}
}Class template year_based_generator3boost::date_time::year_based_generatorBase class for all generators that take a year and produce a date. template<typename date_type>
class year_based_generator {
public:
// typestypedef date_type::calendar_type calendar_type;
typedef calendar_type::year_type year_type;
// construct/copy/destruct
year_based_generator();
~year_based_generator();
// public member functionsvirtual date_type get_date(year_type) const;
};DescriptionThis class is a base class for polymorphic function objects that take a year and produce a concrete date.
<anchor id="year_based_generatorconstruct-copy-destruct"/><computeroutput>year_based_generator</computeroutput> construct/copy/destructyear_based_generator();~year_based_generator();<anchor id="id313666-bb"/><computeroutput>year_based_generator</computeroutput> public member functionsvirtual date_typeget_date(year_type y) const;Class template partial_date3boost::date_time::partial_dateGenerates a date by applying the year to the given month and day. template<typename date_type>
class partial_date
: : public boost::date_time::year_based_generator< date_type >
{
public:
// typestypedef date_type::calendar_type calendar_type;
typedef calendar_type::day_type day_type;
typedef calendar_type::month_type month_type;
typedef calendar_type::year_type year_type;
typedef date_type::duration_type duration_type;
typedef duration_type::duration_rep duration_rep;
// construct/copy/destruct
partial_date(day_type, month_type);
partial_date(duration_rep);
// public member functionsdate_type get_date(year_type) const;
date_typeoperator()(year_type) const;
booloperator==(const partial_date &) const;
booloperator<(const partial_date &) const;
month_type month() const;
day_type day() const;
};DescriptionExample usage: partial_date pd(1, Jan);
partial_date pd2(70);
date d = pd.get_date(2002); //2002-Jan-01
date d2 = pd2.get_date(2002); //2002-Mar-10
<anchor id="partial_dateconstruct-copy-destruct"/><computeroutput>partial_date</computeroutput> construct/copy/destructpartial_date(day_type d, month_type m);partial_date(duration_rep days);Partial date created from number of days into year. Range 1-366. Allowable values range from 1 to 366. 1=Jan1, 366=Dec31. If argument exceeds range, partial_date will be created with closest in-range value. 60 will always be Feb29, if get_date() is called with a non-leap year an exception will be thrown <anchor id="id308312-bb"/><computeroutput>partial_date</computeroutput> public member functionsdate_typeget_date(year_type y) const;Return a concrete date when provided with a year specific year. Will throw an 'invalid_argument' exception if a partial_date object, instantiated with Feb-29, has get_date called with a non-leap year. Example: partial_date pd(29, Feb);
pd.get_date(2003); // throws invalid_argument exception
pg.get_date(2000); // returns 2000-2-29
date_typeoperator()(year_type y) const;booloperator==(const partial_date & rhs) const;booloperator<(const partial_date & rhs) const;month_typemonth() const;day_typeday() const;Class template nth_kday_of_month3boost::date_time::nth_kday_of_monthUseful generator functor for finding holidays. template<typename date_type>
class nth_kday_of_month
: : public boost::date_time::year_based_generator< date_type >
{
public:
// typestypedef date_type::calendar_type calendar_type;
typedef calendar_type::day_of_week_type day_of_week_type;
typedef calendar_type::month_type month_type;
typedef calendar_type::year_type year_type;
typedef date_type::duration_type duration_type;
// construct/copy/destruct
nth_kday_of_month(week_num, day_of_week_type, month_type);
// public member functionsdate_type get_date(year_type) const;
month_type month() const;
week_num nth_week() const;
day_of_week_type day_of_week() const;
constchar * nth_week_as_str() const;
};DescriptionBased on the idea in Cal. Calc. for finding holidays that are the 'first Monday of September'. When instantiated with 'fifth' kday of month, the result will be the last kday of month which can be the fourth or fifth depending on the structure of the month.The algorithm here basically guesses for the first day of the month. Then finds the first day of the correct type. That is, if the first of the month is a Tuesday and it needs Wenesday then we simply increment by a day and then we can add the length of a week until we get to the 'nth kday'. There are probably more efficient algorithms based on using a mod 7, but this one works reasonably well for basic applications. <anchor id="nth_kday_of_monthconstruct-copy-destruct"/><computeroutput>nth_kday_of_month</computeroutput> construct/copy/destructnth_kday_of_month(week_num week_no, day_of_week_type dow, month_type m);<anchor id="id309002-bb"/><computeroutput>nth_kday_of_month</computeroutput> public member functionsdate_typeget_date(year_type y) const;Return a concrete date when provided with a year specific year. month_typemonth() const;week_numnth_week() const;day_of_week_typeday_of_week() const;constchar *nth_week_as_str() const;Class template first_kday_of_month3boost::date_time::first_kday_of_monthUseful generator functor for finding holidays and daylight savings. template<typename date_type>
class first_kday_of_month
: : public boost::date_time::year_based_generator< date_type >
{
public:
// typestypedef date_type::calendar_type calendar_type;
typedef calendar_type::day_of_week_type day_of_week_type;
typedef calendar_type::month_type month_type;
typedef calendar_type::year_type year_type;
typedef date_type::duration_type duration_type;
// construct/copy/destruct
first_kday_of_month(day_of_week_type, month_type);
// public member functionsdate_type get_date(year_type) const;
month_type month() const;
day_of_week_type day_of_week() const;
};DescriptionSimilar to nth_kday_of_month, but requires less paramters <anchor id="first_kday_of_monthconstruct-copy-destruct"/><computeroutput>first_kday_of_month</computeroutput> construct/copy/destructfirst_kday_of_month(day_of_week_type dow, month_type m);Specify the first 'Sunday' in 'April' spec. ParametersdowThe day of week, eg: Sunday, Monday, etc mThe month of the year, eg: Jan, Feb, Mar, etc <anchor id="id390234-bb"/><computeroutput>first_kday_of_month</computeroutput> public member functionsdate_typeget_date(year_type year) const;Return a concrete date when provided with a year specific year. month_typemonth() const;day_of_week_typeday_of_week() const;Class template last_kday_of_month3boost::date_time::last_kday_of_monthCalculate something like Last Sunday of January. template<typename date_type>
class last_kday_of_month
: : public boost::date_time::year_based_generator< date_type >
{
public:
// typestypedef date_type::calendar_type calendar_type;
typedef calendar_type::day_of_week_type day_of_week_type;
typedef calendar_type::month_type month_type;
typedef calendar_type::year_type year_type;
typedef date_type::duration_type duration_type;
// construct/copy/destruct
last_kday_of_month(day_of_week_type, month_type);
// public member functionsdate_type get_date(year_type) const;
month_type month() const;
day_of_week_type day_of_week() const;
};DescriptionUseful generator functor for finding holidays and daylight savings Get the last day of the month and then calculate the difference to the last previous day.
<anchor id="last_kday_of_monthconstruct-copy-destruct"/><computeroutput>last_kday_of_month</computeroutput> construct/copy/destructlast_kday_of_month(day_of_week_type dow, month_type m);Specify the date spec like last 'Sunday' in 'April' spec. ParametersdowThe day of week, eg: Sunday, Monday, etc mThe month of the year, eg: Jan, Feb, Mar, etc <anchor id="id404786-bb"/><computeroutput>last_kday_of_month</computeroutput> public member functionsdate_typeget_date(year_type year) const;Return a concrete date when provided with a year specific year. month_typemonth() const;day_of_week_typeday_of_week() const;Class template first_kday_after3boost::date_time::first_kday_afterCalculate something like "First Sunday after Jan 1,2002. template<typename date_type>
class first_kday_after {
public:
// typestypedef date_type::calendar_type calendar_type;
typedef calendar_type::day_of_week_type day_of_week_type;
typedef date_type::duration_type duration_type;
// construct/copy/destruct
first_kday_after(day_of_week_type);
// public member functionsdate_type get_date(date_type) const;
day_of_week_type day_of_week() const;
};DescriptionDate generator that takes a date and finds kday after typedef boost::date_time::first_kday_after<date> firstkdayafter;
firstkdayafter fkaf(Monday);
fkaf.get_date(date(2002,Feb,1));
<anchor id="first_kday_afterconstruct-copy-destruct"/><computeroutput>first_kday_after</computeroutput> construct/copy/destructfirst_kday_after(day_of_week_type dow);<anchor id="id412058-bb"/><computeroutput>first_kday_after</computeroutput> public member functionsdate_typeget_date(date_type start_day) const;Return next kday given. day_of_week_typeday_of_week() const;Class template first_kday_before3boost::date_time::first_kday_beforeCalculate something like "First Sunday before Jan 1,2002. template<typename date_type>
class first_kday_before {
public:
// typestypedef date_type::calendar_type calendar_type;
typedef calendar_type::day_of_week_type day_of_week_type;
typedef date_type::duration_type duration_type;
// construct/copy/destruct
first_kday_before(day_of_week_type);
// public member functionsdate_type get_date(date_type) const;
day_of_week_type day_of_week() const;
};DescriptionDate generator that takes a date and finds kday after typedef boost::date_time::first_kday_before<date> firstkdaybefore;
firstkdaybefore fkbf(Monday);
fkbf.get_date(date(2002,Feb,1));
<anchor id="first_kday_beforeconstruct-copy-destruct"/><computeroutput>first_kday_before</computeroutput> construct/copy/destructfirst_kday_before(day_of_week_type dow);<anchor id="id391469-bb"/><computeroutput>first_kday_before</computeroutput> public member functionsdate_typeget_date(date_type start_day) const;Return next kday given. day_of_week_typeday_of_week() const;Function template days_until_weekday3boost::date_time::days_until_weekdayCalculates the number of days until the next weekday. template<typename date_type, typename weekday_type>
date_type::duration_type
days_until_weekday(const date_type & d, const weekday_type & wd);DescriptionCalculates the number of days until the next weekday. If the date given falls on a Sunday and the given weekday is Tuesday the result will be 2 days Function template days_before_weekday3boost::date_time::days_before_weekdayCalculates the number of days since the previous weekday. template<typename date_type, typename weekday_type>
date_type::duration_type
days_before_weekday(const date_type & d, const weekday_type & wd);DescriptionCalculates the number of days since the previous weekday If the date given falls on a Sunday and the given weekday is Tuesday the result will be 5 days. The answer will be a positive number because Tuesday is 5 days before Sunday, not -5 days before. Function template next_weekday3boost::date_time::next_weekdayGenerates a date object representing the date of the following weekday from the given date. template<typename date_type, typename weekday_type>
date_type next_weekday(const date_type & d, const weekday_type & wd);DescriptionGenerates a date object representing the date of the following weekday from the given date. If the date given is 2004-May-9 (a Sunday) and the given weekday is Tuesday then the resulting date will be 2004-May-11. Function template previous_weekday3boost::date_time::previous_weekdayGenerates a date object representing the date of the previous weekday from the given date. template<typename date_type, typename weekday_type>
date_type previous_weekday(const date_type & d, const weekday_type & wd);DescriptionGenerates a date object representing the date of the previous weekday from the given date. If the date given is 2004-May-9 (a Sunday) and the given weekday is Tuesday then the resulting date will be 2004-May-4. Header <<ulink url="../../boost/date_time/date_iterator.hpp">boost/date_time/date_iterator.hpp</ulink>>namespace boost {
namespace date_time {
template<typename date_type> class date_itr_base;
template<typename offset_functor, typename date_type> class date_itr;
// An iterator over dates with varying resolution (day, week, month, year, etc). enumdate_resolutions { day, week, months, year, decade, century,
NumDateResolutions };
}
}Class template date_itr_base3boost::date_time::date_itr_baseBase date iterator type. template<typename date_type>
class date_itr_base {
public:
// typestypedef date_type::duration_type duration_type;
typedef date_type value_type;
typedef std::input_iterator_tag iterator_category;
// construct/copy/destruct
date_itr_base(date_type);
~date_itr_base();
// public member functionsdate_itr_base &operator++() ;
date_itr_base &operator--() ;
virtual duration_type get_offset(const date_type &) const;
virtual duration_type get_neg_offset(const date_type &) const;
date_typeoperator *() ;
date_type *operator->() ;
booloperator<(const date_type &) ;
booloperator<=(const date_type &) ;
booloperator>(const date_type &) ;
booloperator>=(const date_type &) ;
booloperator==(const date_type &) ;
booloperator!=(const date_type &) ;
};DescriptionThis class provides the skeleton for the creation of iterators. New and interesting interators can be created by plugging in a new function that derives the next value from the current state. generation of various types of -based information.Template Parametersdate_typeThe date_type is a concrete date_type. The date_type must define a duration_type and a calendar_type. <anchor id="date_itr_baseconstruct-copy-destruct"/><computeroutput>date_itr_base</computeroutput> construct/copy/destructdate_itr_base(date_type d);~date_itr_base();<anchor id="id405036-bb"/><computeroutput>date_itr_base</computeroutput> public member functionsdate_itr_base &operator++() ;date_itr_base &operator--() ;virtual duration_typeget_offset(const date_type & current) const;virtual duration_typeget_neg_offset(const date_type & current) const;date_typeoperator *() ;date_type *operator->() ;booloperator<(const date_type & d) ;booloperator<=(const date_type & d) ;booloperator>(const date_type & d) ;booloperator>=(const date_type & d) ;booloperator==(const date_type & d) ;booloperator!=(const date_type & d) ;Class template date_itr3boost::date_time::date_itrOverrides the base date iterator providing hook for functors. template<typename offset_functor, typename date_type>
class date_itr : public boost::date_time::date_itr_base< date_type > {
public:
// typestypedef date_type::duration_type duration_type;
// construct/copy/destruct
date_itr(date_type, int = 1);
// public member functions// private member functionsvirtual duration_type get_offset(const date_type &) const;
virtual duration_type get_neg_offset(const date_type &) const;
};Description<anchor id="date_itrconstruct-copy-destruct"/><computeroutput>date_itr</computeroutput> construct/copy/destructdate_itr(date_type d, int factor = 1);<anchor id="id354910-bb"/><computeroutput>date_itr</computeroutput> public member functions<anchor id="id359787-bb"/><computeroutput>date_itr</computeroutput> private member functionsvirtual duration_typeget_offset(const date_type & current) const;virtual duration_typeget_neg_offset(const date_type & current) const;Header <<ulink url="../../boost/date_time/date_names_put.hpp">boost/date_time/date_names_put.hpp</ulink>>namespace boost {
namespace date_time {
template<typename Config, typename charT = char,
typename OutputIterator = std::ostreambuf_iterator<charT> >
class date_names_put;
template<typename Config, typename charT = char,
typename OutputIterator = std::ostreambuf_iterator<charT> >
class all_date_names_put;
}
}Class template date_names_put3boost::date_time::date_names_putOutput facet base class for gregorian dates. template<typename Config, typename charT = char,
typename OutputIterator = std::ostreambuf_iterator<charT> >
class date_names_put {
public:
// typestypedef OutputIterator iter_type;
typedef Config::month_type month_type;
typedef Config::month_enum month_enum;
typedef Config::weekday_enum weekday_enum;
typedef Config::special_value_enum special_value_enum;
typedef std::basic_string< charT > string_type;
// construct/copy/destruct
date_names_put();
// public member functionsvoid put_special_value(iter_type &, special_value_enum) const;
void put_month_short(iter_type &, month_enum) const;
void put_month_long(iter_type &, month_enum) const;
void put_weekday_short(iter_type &, weekday_enum) const;
void put_weekday_long(iter_type &, weekday_enum) const;
bool has_date_sep_chars() const;
void year_sep_char(iter_type &) const;
void month_sep_char(iter_type &) const;
void day_sep_char(iter_type &) const;
ymd_order_spec date_order() const;
month_format_spec month_format() const;
// protected member functionsvirtualvoid do_put_month_short(iter_type &, month_enum) const;
virtualvoid do_put_month_long(iter_type &, month_enum) const;
virtualvoid do_put_special_value(iter_type &, special_value_enum) const;
virtualvoid do_put_weekday_short(iter_type &, weekday_enum) const;
virtualvoid do_put_weekday_long(iter_type &, weekday_enum) const;
virtualbool do_has_date_sep_chars() const;
virtualvoid do_year_sep_char(iter_type &) const;
virtualvoid do_month_sep_char(iter_type &) const;
virtualvoid do_day_sep_char(iter_type &) const;
virtual ymd_order_spec do_date_order() const;
virtual month_format_spec do_month_format() const;
void put_string(iter_type &, const charT *const) const;
void put_string(iter_type &, const string_type &) const;
static std::locale::id id;
};DescriptionThis class is a base class for date facets used to localize the names of months and the names of days in the week.Requirements of Configdefine an enumeration month_enum that enumerates the months. The enumeration should be '1' based eg: Jan==1define as_short_string and as_long_string(see langer & kreft p334). <anchor id="date_names_putconstruct-copy-destruct"/><computeroutput>date_names_put</computeroutput> construct/copy/destructdate_names_put();<anchor id="id399644-bb"/><computeroutput>date_names_put</computeroutput> public member functionsvoidput_special_value(iter_type & oitr, special_value_enum sv) const;voidput_month_short(iter_type & oitr, month_enum moy) const;voidput_month_long(iter_type & oitr, month_enum moy) const;voidput_weekday_short(iter_type & oitr, weekday_enum wd) const;voidput_weekday_long(iter_type & oitr, weekday_enum wd) const;boolhas_date_sep_chars() const;voidyear_sep_char(iter_type & oitr) const;voidmonth_sep_char(iter_type & oitr) const;char between year-month voidday_sep_char(iter_type & oitr) const;Char to separate month-day. ymd_order_specdate_order() const;Determines the order to put the date elements. month_format_specmonth_format() const;Determines if month is displayed as integer, short or long string. <anchor id="id429109-bb"/><computeroutput>date_names_put</computeroutput> protected member functionsvirtualvoiddo_put_month_short(iter_type & oitr, month_enum moy) const;Default facet implementation uses month_type defaults. virtualvoiddo_put_month_long(iter_type & oitr, month_enum moy) const;Default facet implementation uses month_type defaults. virtualvoiddo_put_special_value(iter_type & oitr, special_value_enum sv) const;Default facet implementation for special value types. virtualvoiddo_put_weekday_short(iter_type & , weekday_enum ) const;virtualvoiddo_put_weekday_long(iter_type & , weekday_enum ) const;virtualbooldo_has_date_sep_chars() const;virtualvoiddo_year_sep_char(iter_type & oitr) const;virtualvoiddo_month_sep_char(iter_type & oitr) const;char between year-month virtualvoiddo_day_sep_char(iter_type & oitr) const;Char to separate month-day. virtual ymd_order_specdo_date_order() const;Default for date order. virtual month_format_specdo_month_format() const;Default month format. voidput_string(iter_type & oi, const charT *const s) const;voidput_string(iter_type & oi, const string_type & s1) const;Class template all_date_names_put3boost::date_time::all_date_names_putAn date name output facet that takes an array of char* to define strings. template<typename Config, typename charT = char,
typename OutputIterator = std::ostreambuf_iterator<charT> >
class all_date_names_put : public boost::date_time::date_names_put< Config, charT, OutputIterator >
{
public:
// typestypedef OutputIterator iter_type;
typedef Config::month_enum month_enum;
typedef Config::weekday_enum weekday_enum;
typedef Config::special_value_enum special_value_enum;
// construct/copy/destruct
all_date_names_put(const charT *const, const charT *const,
const charT *const, const charT *const,
const charT *const, charT = '-',
ymd_order_spec = ymd_order_iso,
month_format_spec = month_as_short_string);
// public member functionsconst charT *const * get_short_month_names() const;
const charT *const * get_long_month_names() const;
const charT *const * get_special_value_names() const;
const charT *const * get_short_weekday_names() const;
const charT *const * get_long_weekday_names() const;
// protected member functionsvirtualvoid do_put_month_short(iter_type &, month_enum) const;
virtualvoid do_put_month_long(iter_type &, month_enum) const;
virtualvoid do_put_special_value(iter_type &, special_value_enum) const;
virtualvoid do_put_weekday_short(iter_type &, weekday_enum) const;
virtualvoid do_put_weekday_long(iter_type &, weekday_enum) const;
virtualvoid do_month_sep_char(iter_type &) const;
virtualvoid do_day_sep_char(iter_type &) const;
virtual ymd_order_spec do_date_order() const;
virtual month_format_spec do_month_format() const;
};Description<anchor id="all_date_names_putconstruct-copy-destruct"/><computeroutput>all_date_names_put</computeroutput> construct/copy/destructall_date_names_put(const charT *const month_short_names,
const charT *const month_long_names,
const charT *const special_value_names,
const charT *const weekday_short_names,
const charT *const weekday_long_names,
charT separator_char = '-',
ymd_order_spec order_spec = ymd_order_iso,
month_format_spec month_format = month_as_short_string);<anchor id="id330609-bb"/><computeroutput>all_date_names_put</computeroutput> public member functionsconst charT *const *get_short_month_names() const;const charT *const *get_long_month_names() const;const charT *const *get_special_value_names() const;const charT *const *get_short_weekday_names() const;const charT *const *get_long_weekday_names() const;<anchor id="id352064-bb"/><computeroutput>all_date_names_put</computeroutput> protected member functionsvirtualvoiddo_put_month_short(iter_type & oitr, month_enum moy) const;Generic facet that takes array of chars. virtualvoiddo_put_month_long(iter_type & oitr, month_enum moy) const;Long month names. virtualvoiddo_put_special_value(iter_type & oitr, special_value_enum sv) const;Special values names. virtualvoiddo_put_weekday_short(iter_type & oitr, weekday_enum wd) const;virtualvoiddo_put_weekday_long(iter_type & oitr, weekday_enum wd) const;virtualvoiddo_month_sep_char(iter_type & oitr) const;char between year-month virtualvoiddo_day_sep_char(iter_type & oitr) const;Char to separate month-day. virtual ymd_order_specdo_date_order() const;Set the date ordering. virtual month_format_specdo_month_format() const;Set the date ordering. Header <<ulink url="../../boost/date_time/dst_rules.hpp">boost/date_time/dst_rules.hpp</ulink>>Contains template class to provide static dst rule calculationsnamespace boost {
namespace date_time {
template<typename date_type_, typename time_duration_type_>
class dst_calculator;
template<typename date_type, typename time_duration_type,
typename dst_traits>
class dst_calc_engine;
template<typename date_type_, typename time_duration_type_,
unsignedint dst_start_offset_minutes = ,
short dst_length_minutes = >
class us_dst_rules;
template<typename date_type_, typename time_duration_type_>
class null_dst_rules;
enumtime_is_dst_result { is_not_in_dst, is_in_dst, ambiguous,
invalid_time_label };
}
}Class template dst_calculator3boost::date_time::dst_calculatorDynamic class used to caluclate dst transition information. template<typename date_type_, typename time_duration_type_>
class dst_calculator {
public:
// typestypedef time_duration_type_ time_duration_type;
typedef date_type_ date_type;
// public static functionstime_is_dst_result
process_local_dst_start_day(const time_duration_type &, unsignedint, long) ;
time_is_dst_result
process_local_dst_end_day(const time_duration_type &, unsignedint, long) ;
time_is_dst_result
local_is_dst(const date_type &, const time_duration_type &,
const date_type &, unsignedint, const date_type &,
unsignedint, long) ;
};Description<anchor id="id419715-bb"/><computeroutput>dst_calculator</computeroutput> public static functionstime_is_dst_resultprocess_local_dst_start_day(const time_duration_type & time_of_day,
unsignedint dst_start_offset_minutes,
long dst_length_minutes) ;Check the local time offset when on dst start day. On this dst transition, the time label between the transition boundary and the boudary + the offset are invalid times. If before the boundary then still not in dst.
Parametersdst_length_minutesNumber of minutes to adjust clock forward dst_start_offset_minutesLocal day offset for start of dst time_of_dayTime offset in the day for the local time time_is_dst_resultprocess_local_dst_end_day(const time_duration_type & time_of_day,
unsignedint dst_end_offset_minutes,
long dst_length_minutes) ;Check the local time offset when on the last day of dst. This is the calculation for the DST end day. On that day times prior to the conversion time - dst_length (1 am in US) are still in dst. Times between the above and the switch time are ambiguous. Times after the start_offset are not in dst.
Parametersdst_end_offset_minutesLocal time of day for end of dst time_of_dayTime offset in the day for the local time time_is_dst_resultlocal_is_dst(const date_type & current_day,
const time_duration_type & time_of_day,
const date_type & dst_start_day,
unsignedint dst_start_offset_minutes,
const date_type & dst_end_day,
unsignedint dst_end_offset_minutes, long dst_length_minutes) ;Calculates if the given local time is dst or not. Determines if the time is really in DST or not. Also checks for invalid and ambiguous.
Parameterscurrent_dayThe day to check for dst dst_end_dayEnding day of dst for the given locality dst_end_offset_minutesOffset within day given in dst for dst boundary (eg 120 for US which is 02:00:00) dst_length_minutesLength of dst adjusment (eg: 60 for US) dst_start_dayStarting day of dst for the given locality dst_start_offset_minutesOffset within day for dst boundary (eg 120 for US which is 02:00:00) time_of_dayTime offset within the day to check Class template dst_calc_engine3boost::date_time::dst_calc_engineCompile-time configurable daylight savings time calculation engine. template<typename date_type, typename time_duration_type, typename dst_traits>
class dst_calc_engine {
public:
// typestypedef date_type::year_type year_type;
typedef date_type::calendar_type calendar_type;
typedef dst_calculator< date_type, time_duration_type > dstcalc;
// public static functionstime_is_dst_result
local_is_dst(const date_type &, const time_duration_type &) ;
bool is_dst_boundary_day(date_type) ;
time_duration_type dst_offset() ;
date_type local_dst_start_day(year_type) ;
date_type local_dst_end_day(year_type) ;
};Description<anchor id="id389178-bb"/><computeroutput>dst_calc_engine</computeroutput> public static functionstime_is_dst_resultlocal_is_dst(const date_type & d, const time_duration_type & td) ;Calculates if the given local time is dst or not. Determines if the time is really in DST or not. Also checks for invalid and ambiguous.
boolis_dst_boundary_day(date_type d) ;time_duration_typedst_offset() ;The time of day for the dst transition (eg: typically 01:00:00 or 02:00:00). date_typelocal_dst_start_day(year_type year) ;date_typelocal_dst_end_day(year_type year) ;Class template us_dst_rules3boost::date_time::us_dst_rulesDepricated: Class to calculate dst boundaries for US time zones. template<typename date_type_, typename time_duration_type_,
unsignedint dst_start_offset_minutes = ,
short dst_length_minutes = >
class us_dst_rules {
public:
// typestypedef time_duration_type_ time_duration_type;
typedef date_type_ date_type;
typedef date_type::year_type year_type;
typedef date_type::calendar_type calendar_type;
typedef date_time::last_kday_of_month< date_type > lkday;
typedef date_time::first_kday_of_month< date_type > fkday;
typedef dst_calculator< date_type, time_duration_type > dstcalc;
// public static functionstime_is_dst_result
local_is_dst(const date_type &, const time_duration_type &) ;
bool is_dst_boundary_day(date_type) ;
date_type local_dst_start_day(year_type) ;
date_type local_dst_end_day(year_type) ;
time_duration_type dst_offset() ;
};Description<anchor id="id386155-bb"/><computeroutput>us_dst_rules</computeroutput> public static functionstime_is_dst_resultlocal_is_dst(const date_type & d, const time_duration_type & td) ;Calculates if the given local time is dst or not. Determines if the time is really in DST or not. Also checks for invalid and ambiguous.
boolis_dst_boundary_day(date_type d) ;date_typelocal_dst_start_day(year_type year) ;date_typelocal_dst_end_day(year_type year) ;time_duration_typedst_offset() ;Class template null_dst_rules3boost::date_time::null_dst_rulesUsed for local time adjustments in places that don't use dst. template<typename date_type_, typename time_duration_type_>
class null_dst_rules {
public:
// typestypedef time_duration_type_ time_duration_type;
typedef date_type_ date_type;
// public static functionstime_is_dst_result
local_is_dst(const date_type &, const time_duration_type &) ;
time_is_dst_result
utc_is_dst(const date_type &, const time_duration_type &) ;
bool is_dst_boundary_day(date_type) ;
time_duration_type dst_offset() ;
};Description<anchor id="id300974-bb"/><computeroutput>null_dst_rules</computeroutput> public static functionstime_is_dst_resultlocal_is_dst(const date_type & , const time_duration_type & ) ;Calculates if the given local time is dst or not. time_is_dst_resultutc_is_dst(const date_type & , const time_duration_type & ) ;Calculates if the given utc time is in dst. boolis_dst_boundary_day(date_type d) ;time_duration_typedst_offset() ;Header <<ulink url="../../boost/date_time/dst_transition_generators.hpp">boost/date_time/dst_transition_generators.hpp</ulink>>namespace boost {
namespace date_time {
template<typename date_type> class dst_day_calc_rule;
template<typename spec> class day_calc_dst_rule;
}
}Class template dst_day_calc_rule3boost::date_time::dst_day_calc_ruleDefines base interface for calculating start and end date of daylight savings. template<typename date_type>
class dst_day_calc_rule {
public:
// typestypedef date_type::year_type year_type;
// construct/copy/destruct
~dst_day_calc_rule();
// public member functionsvirtual date_type start_day(year_type) const;
virtual date_type end_day(year_type) const;
};Description<anchor id="dst_day_calc_ruleconstruct-copy-destruct"/><computeroutput>dst_day_calc_rule</computeroutput> construct/copy/destruct~dst_day_calc_rule();<anchor id="id425419-bb"/><computeroutput>dst_day_calc_rule</computeroutput> public member functionsvirtual date_typestart_day(year_type y) const;virtual date_typeend_day(year_type y) const;Class template day_calc_dst_rule3boost::date_time::day_calc_dst_ruleCanonical form for a class that provides day rule calculation. template<typename spec>
class day_calc_dst_rule
: : public boost::date_time::dst_day_calc_rule< spec::date_type >
{
public:
// typestypedef spec::date_type date_type;
typedef date_type::year_type year_type;
typedef spec::start_rule start_rule;
typedef spec::end_rule end_rule;
// construct/copy/destruct
day_calc_dst_rule(start_rule, end_rule);
// public member functionsvirtual date_type start_day(year_type) const;
virtual date_type end_day(year_type) const;
};DescriptionThis class is used to generate specific sets of dst rules<anchor id="day_calc_dst_ruleconstruct-copy-destruct"/><computeroutput>day_calc_dst_rule</computeroutput> construct/copy/destructday_calc_dst_rule(start_rule dst_start, end_rule dst_end);<anchor id="id396452-bb"/><computeroutput>day_calc_dst_rule</computeroutput> public member functionsvirtual date_typestart_day(year_type y) const;virtual date_typeend_day(year_type y) const;Header <<ulink url="../../boost/date_time/filetime_functions.hpp">boost/date_time/filetime_functions.hpp</ulink>>Function(s) for converting between a FILETIME structure and a time object. This file is only available on systems that have BOOST_HAS_FTIME defined.namespace boost {
namespace date_time {
template<typename time_type> time_type time_from_ftime(const FILETIME &);
}
}Function template time_from_ftime3boost::date_time::time_from_ftimeCreate a time object from an initialized FILETIME struct. template<typename time_type> time_type time_from_ftime(const FILETIME & ft);DescriptionCreate a time object from an initialized FILETIME struct. A FILETIME struct holds 100-nanosecond units (0.0000001). When built with microsecond resolution the FILETIME's sub second value will be truncated. Nanosecond resolution has no truncation. Header <<ulink url="../../boost/date_time/gregorian_calendar.hpp">boost/date_time/gregorian_calendar.hpp</ulink>>namespace boost {
namespace date_time {
template<typename ymd_type_, typename date_int_type_>
class gregorian_calendar_base;
}
}Class template gregorian_calendar_base3boost::date_time::gregorian_calendar_baseAn implementation of the Gregorian calendar. template<typename ymd_type_, typename date_int_type_>
class gregorian_calendar_base {
public:
// typestypedef ymd_type_ ymd_type; // define a type a date split into components typedef ymd_type::month_type month_type; // define a type for representing months typedef ymd_type::day_type day_type; // define a type for representing days typedef ymd_type::year_type year_type; // Type to hold a stand alone year value (eg: 2002). typedef date_int_type_ date_int_type; // Define the integer type to use for internal calculations. // public static functionsunsignedshort day_of_week(const ymd_type &) ;
int week_number(const ymd_type &) ;
date_int_type day_number(const ymd_type &) ;
date_int_type julian_day_number(const ymd_type &) ;
long modjulian_day_number(const ymd_type &) ;
ymd_type from_day_number(date_int_type) ;
ymd_type from_julian_day_number(date_int_type) ;
ymd_type from_modjulian_day_number(long) ;
bool is_leap_year(year_type) ;
unsignedshort end_of_month_day(year_type, month_type) ;
ymd_type epoch() ;
unsignedshort days_in_week() ;
};DescriptionThis is a parameterized implementation of a proleptic Gregorian Calendar that can be used in the creation of date systems or just to perform calculations. All the methods of this class are static functions, so the intent is to never create instances of this class.
<anchor id="id423726-bb"/><computeroutput>gregorian_calendar_base</computeroutput> public static functionsunsignedshortday_of_week(const ymd_type & ymd) ;intweek_number(const ymd_type & ymd) ;date_int_typeday_number(const ymd_type & ymd) ;date_int_typejulian_day_number(const ymd_type & ymd) ;longmodjulian_day_number(const ymd_type & ymd) ;ymd_typefrom_day_number(date_int_type ) ;ymd_typefrom_julian_day_number(date_int_type ) ;ymd_typefrom_modjulian_day_number(long ) ;boolis_leap_year(year_type ) ;unsignedshortend_of_month_day(year_type y, month_type m) ;ymd_typeepoch() ;unsignedshortdays_in_week() ;Header <<ulink url="../../boost/date_time/int_adapter.hpp">boost/date_time/int_adapter.hpp</ulink>>namespace boost {
namespace date_time {
template<typename int_type_> class int_adapter;
template<typename charT, typename traits, typename int_type>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > &,
const int_adapter< int_type > &);
}
}Class template int_adapter3boost::date_time::int_adapterAdapter to create integer types with +-infinity, and not a value. template<typename int_type_>
class int_adapter {
public:
// typestypedef int_type_ int_type;
// construct/copy/destruct
int_adapter(int_type);
// public member functionsbool is_infinity() const;
bool is_pos_infinity() const;
bool is_neg_infinity() const;
bool is_nan() const;
bool is_special() const;
booloperator==(const int_adapter &) const;
booloperator==(constint &) const;
booloperator!=(const int_adapter &) const;
booloperator!=(constint &) const;
booloperator<(const int_adapter &) const;
booloperator<(constint &) const;
booloperator>(const int_adapter &) const;
int_type as_number() const;
special_values as_special() const;
template<typename rhs_type>
int_adapteroperator+(const int_adapter< rhs_type > &) const;
int_adapteroperator+(const int_type) const;
template<typename rhs_type>
int_adapteroperator-(const int_adapter< rhs_type > &) const;
int_adapteroperator-(const int_type) const;
int_adapteroperator *(const int_adapter &) const;
int_adapteroperator *(constint) const;
int_adapteroperator/(const int_adapter &) const;
int_adapteroperator/(constint) const;
int_adapteroperator%(const int_adapter &) const;
int_adapteroperator%(constint) const;
// public static functionsbool has_infinity() ;
const int_adapter pos_infinity() ;
const int_adapter neg_infinity() ;
const int_adapter not_a_number() ;
int_adapter max BOOST_PREVENT_MACRO_SUBSTITUTION() ;
int_adapter min BOOST_PREVENT_MACRO_SUBSTITUTION() ;
int_adapter from_special(special_values) ;
bool is_inf(int_type) ;
bool is_neg_inf(int_type) ;
bool is_pos_inf(int_type) ;
bool is_not_a_number(int_type) ;
special_values to_special(int_type) ;
int_type maxcount() ;
// private member functionsint compare(const int_adapter &) const;
int_adapter mult_div_specials(const int_adapter &) const;
int_adapter mult_div_specials(constint &) const;
};DescriptionThis class is used internally in counted date/time representations. It adds the floating point like features of infinities and not a number. It also provides mathmatical operations with consideration to special values following these rules: +infinity - infinity == Not A Number (NAN)
infinity * non-zero == infinity
infinity * zero == NAN
+infinity * -integer == -infinity
infinity / infinity == NAN
infinity * infinity == infinity
*
<anchor id="int_adapterconstruct-copy-destruct"/><computeroutput>int_adapter</computeroutput> construct/copy/destructint_adapter(int_type v);<anchor id="id323624-bb"/><computeroutput>int_adapter</computeroutput> public member functionsboolis_infinity() const;boolis_pos_infinity() const;boolis_neg_infinity() const;boolis_nan() const;boolis_special() const;booloperator==(const int_adapter & rhs) const;booloperator==(constint & rhs) const;booloperator!=(const int_adapter & rhs) const;booloperator!=(constint & rhs) const;booloperator<(const int_adapter & rhs) const;booloperator<(constint & rhs) const;booloperator>(const int_adapter & rhs) const;int_typeas_number() const;special_valuesas_special() const;Returns either special value type or is_not_special. template<typename rhs_type>
int_adapteroperator+(const int_adapter< rhs_type > & rhs) const;Operator allows for adding dissimilar int_adapter types. The return type will match that of the the calling object's type int_adapteroperator+(const int_type rhs) const;template<typename rhs_type>
int_adapteroperator-(const int_adapter< rhs_type > & rhs) const;Operator allows for subtracting dissimilar int_adapter types. The return type will match that of the the calling object's type int_adapteroperator-(const int_type rhs) const;int_adapteroperator *(const int_adapter & rhs) const;int_adapteroperator *(constint rhs) const;Provided for cases when automatic conversion from 'int' to 'int_adapter' causes incorrect results. int_adapteroperator/(const int_adapter & rhs) const;int_adapteroperator/(constint rhs) const;Provided for cases when automatic conversion from 'int' to 'int_adapter' causes incorrect results. int_adapteroperator%(const int_adapter & rhs) const;int_adapteroperator%(constint rhs) const;Provided for cases when automatic conversion from 'int' to 'int_adapter' causes incorrect results. <anchor id="id321702-bb"/><computeroutput>int_adapter</computeroutput> public static functionsboolhas_infinity() ;const int_adapterpos_infinity() ;const int_adapterneg_infinity() ;const int_adapternot_a_number() ;int_adapter maxBOOST_PREVENT_MACRO_SUBSTITUTION() ;int_adapter minBOOST_PREVENT_MACRO_SUBSTITUTION() ;int_adapterfrom_special(special_values sv) ;boolis_inf(int_type v) ;boolis_neg_inf(int_type v) ;boolis_pos_inf(int_type v) ;boolis_not_a_number(int_type v) ;special_valuesto_special(int_type v) ;Returns either special value type or is_not_special. int_typemaxcount() ;<anchor id="id346826-bb"/><computeroutput>int_adapter</computeroutput> private member functionsintcompare(const int_adapter & rhs) const;returns -1, 0, 1, or 2 if 'this' is <, ==, >, or 'nan comparison' rhs int_adaptermult_div_specials(const int_adapter & rhs) const;Assumes at least 'this' or 'rhs' is a special value. int_adaptermult_div_specials(constint & rhs) const;Assumes 'this' is a special value. Function template operator<<3boost::date_time::operator<<template<typename charT, typename traits, typename int_type>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os,
const int_adapter< int_type > & ia);DescriptionExpected output is either a numeric representation or a special values representation.
Ex. "12", "+infinity", "not-a-number", etc. Header <<ulink url="../../boost/date_time/iso_format.hpp">boost/date_time/iso_format.hpp</ulink>>namespace boost {
namespace date_time {
template<typename charT> class iso_format_base;
template<> class iso_format_base<wchar_t>;
template<typename charT> class iso_format;
template<typename charT> class iso_extended_format;
}
}Class template iso_format_base3boost::date_time::iso_format_baseClass to provide common iso formatting spec. template<typename charT>
class iso_format_base {
public:
// public static functionsmonth_format_spec month_format() ;
const charT * not_a_date() ;
const charT * pos_infinity() ;
const charT * neg_infinity() ;
charT year_sep_char() ;
charT month_sep_char() ;
charT day_sep_char() ;
charT hour_sep_char() ;
charT minute_sep_char() ;
charT second_sep_char() ;
charT period_start_char() ;
charT time_start_char() ;
charT week_start_char() ;
charT period_sep_char() ;
charT time_sep_char() ;
charT fractional_time_sep_char() ;
bool is_component_sep(charT) ;
bool is_fractional_time_sep(charT) ;
bool is_timezone_sep(charT) ;
charT element_sep_char() ;
};Description<anchor id="id285752-bb"/><computeroutput>iso_format_base</computeroutput> public static functionsmonth_format_specmonth_format() ;Describe month format -- its an integer in iso format. const charT *not_a_date() ;String used printed is date is invalid. const charT *pos_infinity() ;String used to for positive infinity value. const charT *neg_infinity() ;String used to for positive infinity value. charTyear_sep_char() ;ISO char for a year -- used in durations. charTmonth_sep_char() ;ISO char for a month. charTday_sep_char() ;ISO char for a day. charThour_sep_char() ;char for minute charTminute_sep_char() ;char for minute charTsecond_sep_char() ;char for second charTperiod_start_char() ;ISO char for a period. charTtime_start_char() ;Used in time in mixed strings to set start of time. charTweek_start_char() ;Used in mixed strings to identify start of a week number. charTperiod_sep_char() ;Separators for periods. charTtime_sep_char() ;Separator for hh:mm:ss. charTfractional_time_sep_char() ;Preferred Separator for hh:mm:ss,decimal_fraction. boolis_component_sep(charT sep) ;boolis_fractional_time_sep(charT sep) ;boolis_timezone_sep(charT sep) ;charTelement_sep_char() ;SpecializationsClass iso_format_base<wchar_t>Class iso_format_base<wchar_t>3boost::date_time::iso_format_base<wchar_t>Class to provide common iso formatting spec. class iso_format_base<wchar_t> {
public:
// public static functionsmonth_format_spec month_format() ;
constwchar_t * not_a_date() ;
constwchar_t * pos_infinity() ;
constwchar_t * neg_infinity() ;
wchar_t year_sep_char() ;
wchar_t month_sep_char() ;
wchar_t day_sep_char() ;
wchar_t hour_sep_char() ;
wchar_t minute_sep_char() ;
wchar_t second_sep_char() ;
wchar_t period_start_char() ;
wchar_t time_start_char() ;
wchar_t week_start_char() ;
wchar_t period_sep_char() ;
wchar_t time_sep_char() ;
wchar_t fractional_time_sep_char() ;
bool is_component_sep(wchar_t) ;
bool is_fractional_time_sep(wchar_t) ;
bool is_timezone_sep(wchar_t) ;
wchar_t element_sep_char() ;
};Description<anchor id="id401187-bb"/><computeroutput>iso_format_base</computeroutput> public static functionsmonth_format_specmonth_format() ;Describe month format -- its an integer in iso format. constwchar_t *not_a_date() ;String used printed is date is invalid. constwchar_t *pos_infinity() ;String used to for positive infinity value. constwchar_t *neg_infinity() ;String used to for positive infinity value. wchar_tyear_sep_char() ;ISO char for a year -- used in durations. wchar_tmonth_sep_char() ;ISO char for a month. wchar_tday_sep_char() ;ISO char for a day. wchar_thour_sep_char() ;char for minute wchar_tminute_sep_char() ;char for minute wchar_tsecond_sep_char() ;char for second wchar_tperiod_start_char() ;ISO char for a period. wchar_ttime_start_char() ;Used in time in mixed strings to set start of time. wchar_tweek_start_char() ;Used in mixed strings to identify start of a week number. wchar_tperiod_sep_char() ;Separators for periods. wchar_ttime_sep_char() ;Separator for hh:mm:ss. wchar_tfractional_time_sep_char() ;Preferred Separator for hh:mm:ss,decimal_fraction. boolis_component_sep(wchar_t sep) ;boolis_fractional_time_sep(wchar_t sep) ;boolis_timezone_sep(wchar_t sep) ;wchar_telement_sep_char() ;Class template iso_format3boost::date_time::iso_formatFormat description for iso normal YYYYMMDD. template<typename charT>
class iso_format : public boost::date_time::iso_format_base< charT > {
public:
// public static functionsbool has_date_sep_chars() ;
};Description<anchor id="id289015-bb"/><computeroutput>iso_format</computeroutput> public static functionsboolhas_date_sep_chars() ;The ios standard format doesn't use char separators. Class template iso_extended_format3boost::date_time::iso_extended_formatExtended format uses seperators YYYY-MM-DD. template<typename charT>
class iso_extended_format
: : public boost::date_time::iso_format_base< charT >
{
public:
// public static functionsbool has_date_sep_chars() ;
};Description<anchor id="id323920-bb"/><computeroutput>iso_extended_format</computeroutput> public static functionsboolhas_date_sep_chars() ;Extended format needs char separators. Header <<ulink url="../../boost/date_time/local_time_adjustor.hpp">boost/date_time/local_time_adjustor.hpp</ulink>>Time adjustment calculations for local timesnamespace boost {
namespace date_time {
template<typename time_duration_type, short hours,
unsignedshort minutes = >
class utc_adjustment;
template<typename time_type, typename dst_rules>
class dynamic_local_time_adjustor;
template<typename time_type, typename dst_rules,
typename utc_offset_rules>
class static_local_time_adjustor;
template<typename time_type, short utc_offset, typename dst_rule>
class local_adjustor;
voiddummy_to_prevent_msvc6_ice();
}
}Class template utc_adjustment3boost::date_time::utc_adjustmentProvides a base offset adjustment from utc. template<typename time_duration_type, short hours, unsignedshort minutes = >
class utc_adjustment {
public:
// public static functionstime_duration_type local_to_utc_base_offset() ;
time_duration_type utc_to_local_base_offset() ;
};Description<anchor id="id302720-bb"/><computeroutput>utc_adjustment</computeroutput> public static functionstime_duration_typelocal_to_utc_base_offset() ;time_duration_typeutc_to_local_base_offset() ;Class template dynamic_local_time_adjustor3boost::date_time::dynamic_local_time_adjustorAllow sliding utc adjustment with fixed dst rules. template<typename time_type, typename dst_rules>
class dynamic_local_time_adjustor {
public:
// typestypedef time_type::time_duration_type time_duration_type;
typedef time_type::date_type date_type;
// construct/copy/destruct
dynamic_local_time_adjustor(time_duration_type);
// public member functionstime_duration_type utc_offset(bool) ;
};Description<anchor id="id418394construct-copy-destruct"/><computeroutput>dynamic_local_time_adjustor</computeroutput> construct/copy/destructdynamic_local_time_adjustor(time_duration_type utc_offset);<anchor id="id391590-bb"/><computeroutput>dynamic_local_time_adjustor</computeroutput> public member functionstime_duration_typeutc_offset(bool is_dst) ;Presumes local time. Class template static_local_time_adjustor3boost::date_time::static_local_time_adjustorEmbed the rules for local time adjustments at compile time. template<typename time_type, typename dst_rules, typename utc_offset_rules>
class static_local_time_adjustor {
public:
// typestypedef time_type::time_duration_type time_duration_type;
typedef time_type::date_type date_type;
// public static functionstime_duration_type utc_to_local_offset(const time_type &) ;
time_duration_type
local_to_utc_offset(const time_type &,
date_time::dst_flags = date_time::calculate) ;
};Description<anchor id="id329177-bb"/><computeroutput>static_local_time_adjustor</computeroutput> public static functionstime_duration_typeutc_to_local_offset(const time_type & t) ;Calculates the offset from a utc time to local based on dst and utc offset.
The logic is as follows. Starting with UTC time use the offset to create a label for an non-dst adjusted local time. Then call dst_rules::local_is_dst with the non adjust local time. The results of this function will either unabiguously decide that the initial local time is in dst or return an illegal or ambiguous result. An illegal result only occurs at the end of dst (where labels are skipped) and indicates that dst has ended. An ambiguous result means that we need to recheck by making a dst adjustment and then rechecking. If the dst offset is added to the utc time and the recheck proves non-ambiguous then we are past the boundary. If it is still ambiguous then we are ahead of the boundary and dst is still in effect.TODO -- check if all dst offsets are positive. If not then the algorithm needs to check for this and reverse the illegal/ambiguous logic. ParameterstUTC time to calculate offset to local time This adjustment depends on the following observations about the workings of the DST boundary offset. Since UTC time labels are monotonically increasing we can determine if a given local time is in DST or not and therefore adjust the offset appropriately.time_duration_typelocal_to_utc_offset(const time_type & t,
date_time::dst_flags dst = date_time::calculate) ;Get the offset to UTC given a local time. Class template local_adjustor3boost::date_time::local_adjustorTemplate that simplifies the creation of local time calculator. template<typename time_type, short utc_offset, typename dst_rule>
class local_adjustor {
public:
// typestypedef time_type::time_duration_type time_duration_type;
typedef time_type::date_type date_type;
typedef static_local_time_adjustor< time_type, dst_rule, utc_adjustment< time_duration_type, utc_offset > > dst_adjustor;
// public static functionstime_type utc_to_local(const time_type &) ;
time_type local_to_utc(const time_type &,
date_time::dst_flags = date_time::calculate) ;
};DescriptionUse this template to create the timezone to utc convertors as required.This class will also work for other regions that don't use dst and have a utc offset which is an integral number of hours.Template Parameters -time_type -- Time class to use -utc_offset -- Number hours local time is adjust from utc -use_dst -- true (default) if region uses dst, false otherwise For example: //eastern timezone is utc-5
typedef date_time::local_adjustor<ptime, -5, us_dst> us_eastern;
typedef date_time::local_adjustor<ptime, -6, us_dst> us_central;
typedef date_time::local_adjustor<ptime, -7, us_dst> us_mountain;
typedef date_time::local_adjustor<ptime, -8, us_dst> us_pacific;
typedef date_time::local_adjustor<ptime, -7, no_dst> us_arizona;
<anchor id="id412017-bb"/><computeroutput>local_adjustor</computeroutput> public static functionstime_typeutc_to_local(const time_type & t) ;Convert a utc time to local time. time_typelocal_to_utc(const time_type & t,
date_time::dst_flags dst = date_time::calculate) ;Convert a local time to utc. Header <<ulink url="../../boost/date_time/local_timezone_defs.hpp">boost/date_time/local_timezone_defs.hpp</ulink>>namespace boost {
namespace date_time {
template<typename date_type> struct us_dst_trait;
template<typename date_type> struct eu_dst_trait;
template<typename date_type> struct uk_dst_trait;
template<typename date_type> struct acst_dst_trait;
}
}Struct template us_dst_trait3boost::date_time::us_dst_traitSpecification for daylight savings start rules in US. template<typename date_type>
struct us_dst_trait {
// typestypedef date_type::day_of_week_type day_of_week_type;
typedef date_type::month_type month_type;
typedef date_time::first_kday_of_month< date_type > start_rule_functor;
typedef date_time::last_kday_of_month< date_type > end_rule_functor;
// public static functionsday_of_week_type start_day() ;
month_type start_month() ;
day_of_week_type end_day() ;
month_type end_month() ;
int dst_start_offset_minutes() ;
int dst_end_offset_minutes() ;
int dst_shift_length_minutes() ;
};DescriptionThis class is used to configure dst_calc_engine template typically as follows: using namespace boost::gregorian;
using namespace boost::posix_time;
typedef us_dst_trait<date> us_dst_traits;
typedef boost::date_time::dst_calc_engine<date, time_duration,
us_dst_traits>
us_dst_calc;
//calculate the 2002 transition day of USA April 7 2002
date dst_start = us_dst_calc::local_dst_start_day(2002);
//calculate the 2002 transition day of USA Oct 27 2002
date dst_end = us_dst_calc::local_dst_end_day(2002);
//check if a local time is in dst or not -- posible answers
//are yes, no, invalid time label, ambiguous
ptime t(...some time...);
if (us_dst::local_is_dst(t.date(), t.time_of_day())
== boost::date_time::is_not_in_dst)
{
}
This generates a type suitable for the calculation of dst transitions for the United States. Of course other templates can be used for other locales. <anchor id="id425487-bb"/><computeroutput>us_dst_trait</computeroutput> public static functionsday_of_week_typestart_day() ;month_typestart_month() ;day_of_week_typeend_day() ;month_typeend_month() ;intdst_start_offset_minutes() ;intdst_end_offset_minutes() ;intdst_shift_length_minutes() ;Struct template eu_dst_trait3boost::date_time::eu_dst_traitRules for daylight savings start in the EU (Last Sun in Mar). template<typename date_type>
struct eu_dst_trait {
// typestypedef date_type::day_of_week_type day_of_week_type;
typedef date_type::month_type month_type;
typedef date_time::last_kday_of_month< date_type > start_rule_functor;
typedef date_time::last_kday_of_month< date_type > end_rule_functor;
// public static functionsday_of_week_type start_day() ;
month_type start_month() ;
day_of_week_type end_day() ;
month_type end_month() ;
int dst_start_offset_minutes() ;
int dst_end_offset_minutes() ;
int dst_shift_length_minutes() ;
};DescriptionThese amount to the following:Start of dst day is last Sunday in MarchEnd day of dst is last Sunday in OctGoing forward switch time is 2:00 am (offset 120 minutes)Going back switch time is 3:00 am (off set 180 minutes)Shift duration is one hour (60 minutes) <anchor id="id320813-bb"/><computeroutput>eu_dst_trait</computeroutput> public static functionsday_of_week_typestart_day() ;month_typestart_month() ;day_of_week_typeend_day() ;month_typeend_month() ;intdst_start_offset_minutes() ;intdst_end_offset_minutes() ;intdst_shift_length_minutes() ;Struct template uk_dst_trait3boost::date_time::uk_dst_traitAlternative dst traits for some parts of the United Kingdom. template<typename date_type>
struct uk_dst_trait : public boost::date_time::eu_dst_trait< date_type > {
// public static functionsint dst_start_offset_minutes() ;
int dst_end_offset_minutes() ;
int dst_shift_length_minutes() ;
};Description<anchor id="id299024-bb"/><computeroutput>uk_dst_trait</computeroutput> public static functionsintdst_start_offset_minutes() ;intdst_end_offset_minutes() ;intdst_shift_length_minutes() ;Struct template acst_dst_trait3boost::date_time::acst_dst_traittemplate<typename date_type>
struct acst_dst_trait {
// typestypedef date_type::day_of_week_type day_of_week_type;
typedef date_type::month_type month_type;
typedef date_time::last_kday_of_month< date_type > start_rule_functor;
typedef date_time::last_kday_of_month< date_type > end_rule_functor;
// public static functionsday_of_week_type start_day() ;
month_type start_month() ;
day_of_week_type end_day() ;
month_type end_month() ;
int dst_start_offset_minutes() ;
int dst_end_offset_minutes() ;
int dst_shift_length_minutes() ;
};Description<anchor id="id344507-bb"/><computeroutput>acst_dst_trait</computeroutput> public static functionsday_of_week_typestart_day() ;month_typestart_month() ;day_of_week_typeend_day() ;month_typeend_month() ;intdst_start_offset_minutes() ;intdst_end_offset_minutes() ;intdst_shift_length_minutes() ;Header <<ulink url="../../boost/date_time/microsec_time_clock.hpp">boost/date_time/microsec_time_clock.hpp</ulink>>This file contains a high resolution time clock implementation.namespace boost {
namespace date_time {
template<typename time_type> class microsec_clock;
}
}Class template microsec_clock3boost::date_time::microsec_clockA clock providing microsecond level resolution. template<typename time_type>
class microsec_clock {
public:
// typestypedef time_type::date_type date_type;
typedef time_type::time_duration_type time_duration_type;
typedef time_duration_type::rep_type resolution_traits_type;
// public static functionstime_type local_time() ;
// private static functionstime_type create_time(timeval *) ;
time_type local_time() ;
time_type create_time(FILETIME &) ;
};DescriptionA high precision clock that measures the local time at a resolution up to microseconds and adjusts to the resolution of the time system. For example, for the a library configuration with nano second resolution, the last 3 places of the fractional seconds will always be 000 since there are 1000 nano-seconds in a micro second. <anchor id="id430932-bb"/><computeroutput>microsec_clock</computeroutput> public static functionstime_typelocal_time() ;Return the local time based on computer clock settings. <anchor id="id427143-bb"/><computeroutput>microsec_clock</computeroutput> private static functionstime_typecreate_time(timeval * tv) ;time_typelocal_time() ;Return the local time based on computer clock settings. time_typecreate_time(FILETIME & ft) ;Header <<ulink url="../../boost/date_time/parse_format_base.hpp">boost/date_time/parse_format_base.hpp</ulink>>namespace boost {
namespace date_time {
// Enum for distinguishing parsing and formatting options. enummonth_format_spec { month_as_integer, month_as_short_string,
month_as_long_string };
enum ymd_order_spec;
}
}Type ymd_order_spec3boost::date_time::ymd_order_specEnum for distinguishing the order of Month, Day, & Year. enum ymd_order_spec { ymd_order_iso, ymd_order_dmy, ymd_order_us };Header <<ulink url="../../boost/date_time/period.hpp">boost/date_time/period.hpp</ulink>>This file contain the implementation of the period abstraction. This is basically the same idea as a range. Although this class is intended for use in the time library, it is pretty close to general enough for other numeric uses.namespace boost {
namespace date_time {
template<typename point_rep, typename duration_rep> class period;
}
}Class template period3boost::date_time::periodProvides generalized period type useful in date-time systems. template<typename point_rep, typename duration_rep>
class period {
public:
// typestypedef point_rep point_type;
typedef duration_rep duration_type;
// construct/copy/destruct
period(point_rep, point_rep);
period(point_rep, duration_rep);
// public member functionspoint_rep begin() const;
point_rep end() const;
point_rep last() const;
duration_rep length() const;
bool is_null() const;
booloperator==(const period &) const;
booloperator<(const period &) const;
void shift(const duration_rep &) ;
bool contains(const point_rep &) const;
bool contains(const period &) const;
bool intersects(const period &) const;
bool is_adjacent(const period &) const;
bool is_before(const point_rep &) const;
bool is_after(const point_rep &) const;
period intersection(const period &) const;
period merge(const period &) const;
period span(const period &) const;
};DescriptionThis template uses a class to represent a time point within the period and another class to represent a duration. As a result, this class is not appropriate for use when the number and duration representation are the same (eg: in the regular number domain).A period can be specified by providing either the starting point and a duration or the starting point and the end point( end is NOT part of the period but 1 unit past it. A period will be "invalid" if either start_point >= end_point or the given duration is < 0. Any valid period will return false for is_null().Zero length periods are considered valid. In this case the start point is exactly 1 unit less than the end point, in other words start is equal to last.In the case that the begin and last are the same, the period has a length of zero units. For example, suppose this is a period of days. That is, each time-point represents a single day. If the start and the last is the same day then the period is zero length.The best way to handle periods is usually to provide a start point and a duration. So, day1 + 7 days is a week period which includes all of the first day and 6 more days (eg: Sun to Sat). <anchor id="periodconstruct-copy-destruct"/><computeroutput>period</computeroutput> construct/copy/destructperiod(point_rep first_point, point_rep end_point);create a period from begin to last eg: [begin,end) If end <= begin then the period will be invalid period(point_rep first_point, duration_rep len);create a period as [begin, begin+len) If len is < 0 then the period will be invalid <anchor id="id342658-bb"/><computeroutput>period</computeroutput> public member functionspoint_repbegin() const;Return the first element in the period. point_repend() const;Return one past the last element. point_replast() const;Return the last item in the period. duration_replength() const;Return the length of the period. boolis_null() const;True if period is ill formed (length less than zero). booloperator==(const period & rhs) const;Equality operator. booloperator<(const period & rhs) const;Strict as defined by rhs.last <= lhs.last. voidshift(const duration_rep & d) ;Shift the start and end by the specified amount. boolcontains(const point_rep & point) const;True if the point is inside the period. boolcontains(const period & other) const;True if this period fully contains (or equals) the other period. boolintersects(const period & other) const;True if the periods overlap in any way. boolis_adjacent(const period & other) const;True if periods are next to each other without a gap. boolis_before(const point_rep & point) const;True if all of the period is prior to the passed point or end <= t. boolis_after(const point_rep & point) const;True if all of the period is prior or t < start. periodintersection(const period & other) const;Returns the period of intersection or invalid range no intersection. periodmerge(const period & other) const;Returns the union of intersecting periods -- or null period. periodspan(const period & other) const;Combine two periods with earliest start and latest end. Combines two periods and any gap between them such that start = min(p1.start, p2.start) end = max(p1.end , p2.end) [---p1---)
[---p2---)
result:
[-----------p3----------)
*
Header <<ulink url="../../boost/date_time/special_defs.hpp">boost/date_time/special_defs.hpp</ulink>>namespace boost {
namespace date_time {
enumspecial_values { not_a_date_time, neg_infin, pos_infin,
min_date_time, max_date_time, not_special,
NumSpecialValues };
}
}Header <<ulink url="../../boost/date_time/time.hpp">boost/date_time/time.hpp</ulink>>This file contains the interface for the time associated classes.namespace boost {
namespace date_time {
template<typename T, typename time_system> class base_time;
}
}Class template base_time3boost::date_time::base_timeRepresentation of a precise moment in time, including the date. template<typename T, typename time_system>
class base_time {
public:
// typestypedef T time_type;
typedef time_system::time_rep_type time_rep_type;
typedef time_system::date_type date_type;
typedef time_system::date_duration_type date_duration_type;
typedef time_system::time_duration_type time_duration_type;
// construct/copy/destruct
base_time(const date_type &, const time_duration_type &,
dst_flags = not_dst);
base_time(const time_rep_type &);
// public member functionsdate_type date() const;
time_duration_type time_of_day() const;
std::string zone_name() const;
bool is_not_a_date_time() const;
bool is_infinity() const;
bool is_pos_infinity() const;
bool is_neg_infinity() const;
booloperator==(const time_type &) const;
booloperator<(const time_type &) const;
time_duration_typeoperator-(const time_type &) const;
time_typeoperator+(const date_duration_type &) const;
time_typeoperator+=(const date_duration_type &) ;
time_typeoperator-(const date_duration_type &) const;
time_typeoperator-=(const date_duration_type &) ;
time_typeoperator+(const time_duration_type &) const;
time_typeoperator+=(const time_duration_type &) ;
time_typeoperator-(const time_duration_type &) const;
time_typeoperator-=(const time_duration_type &) ;
};DescriptionThis class is a skeleton for the interface of a temporal type with a resolution that is higher than a day. It is intended that this class be the base class and that the actual time class be derived using the BN pattern. In this way, the derived class can make decisions such as 'should there be a default constructor' and what should it set its value to, should there be optional constructors say allowing only an time_durations that generate a time from a clock,etc. So, in fact multiple time types can be created for a time_system with different construction policies, and all of them can perform basic operations by only writing a copy constructor. Finally, compiler errors are also shorter.The real behavior of the time class is provided by the time_system template parameter. This class must provide all the logic for addition, subtraction, as well as define all the interface types. <anchor id="base_timeconstruct-copy-destruct"/><computeroutput>base_time</computeroutput> construct/copy/destructbase_time(const date_type & day, const time_duration_type & td,
dst_flags dst = not_dst);base_time(const time_rep_type & rhs);<anchor id="id366790-bb"/><computeroutput>base_time</computeroutput> public member functionsdate_typedate() const;time_duration_typetime_of_day() const;std::stringzone_name() const;boolis_not_a_date_time() const;check to see if date is not a value boolis_infinity() const;check to see if date is one of the infinity values boolis_pos_infinity() const;check to see if date is greater than all possible dates boolis_neg_infinity() const;check to see if date is greater than all possible dates booloperator==(const time_type & rhs) const;Equality operator -- others generated by boost::equality_comparable. booloperator<(const time_type & rhs) const;Equality operator -- others generated by boost::less_than_comparable. time_duration_typeoperator-(const time_type & rhs) const;difference between two times time_typeoperator+(const date_duration_type & dd) const;add date durations time_typeoperator+=(const date_duration_type & dd) ;time_typeoperator-(const date_duration_type & dd) const;subtract date durations time_typeoperator-=(const date_duration_type & dd) ;time_typeoperator+(const time_duration_type & td) const;add time durations time_typeoperator+=(const time_duration_type & td) ;time_typeoperator-(const time_duration_type & rhs) const;subtract time durations time_typeoperator-=(const time_duration_type & td) ;Header <<ulink url="../../boost/date_time/time_clock.hpp">boost/date_time/time_clock.hpp</ulink>>This file contains the interface for clock devices.namespace boost {
namespace date_time {
template<typename date_type, typename time_type> class second_clock;
}
}Class template second_clock3boost::date_time::second_clockA clock providing time level services based on C time_t capabilities. template<typename date_type, typename time_type>
class second_clock {
public:
// typestypedef time_type::time_duration_type time_duration_type;
// public static functionstime_type local_time() ;
time_type universal_time() ;
// private static functionstime_type create_time(::std::tm *) ;
};DescriptionThis clock provides resolution to the 1 second level <anchor id="id428262-bb"/><computeroutput>second_clock</computeroutput> public static functionstime_typelocal_time() ;time_typeuniversal_time() ;Get the current day in universal date as a ymd_type. <anchor id="id337896-bb"/><computeroutput>second_clock</computeroutput> private static functionstime_typecreate_time(::std::tm * current) ;Header <<ulink url="../../boost/date_time/time_defs.hpp">boost/date_time/time_defs.hpp</ulink>>This file contains nice definitions for handling the resoluion of various time reprsentations.namespace boost {
namespace date_time {
// Defines some nice types for handling time level resolutions. enumtime_resolutions { sec, tenth, hundreth, milli, ten_thousandth,
micro, nano, NumResolutions };
// Flags for daylight savings or summer time. enumdst_flags { not_dst, is_dst, calculate };
}
}Header <<ulink url="../../boost/date_time/time_duration.hpp">boost/date_time/time_duration.hpp</ulink>>namespace boost {
namespace date_time {
template<typename T, typename rep_type> class time_duration;
template<typename base_duration, long frac_of_second>
class subsecond_duration;
}
}Class template time_duration3boost::date_time::time_durationRepresents some amount of elapsed time measure to a given resolution. template<typename T, typename rep_type>
class time_duration {
public:
// typestypedef T duration_type;
typedef rep_type traits_type;
typedef rep_type::day_type day_type;
typedef rep_type::hour_type hour_type;
typedef rep_type::min_type min_type;
typedef rep_type::sec_type sec_type;
typedef rep_type::fractional_seconds_type fractional_seconds_type;
typedef rep_type::tick_type tick_type;
typedef rep_type::impl_type impl_type;
// construct/copy/destruct
time_duration();
time_duration(hour_type, min_type, sec_type = 0,
fractional_seconds_type = 0);
time_duration(const time_duration< T, rep_type > &);
time_duration(special_values);
time_duration(impl_type);
// public member functionshour_type hours() const;
min_type minutes() const;
sec_type seconds() const;
sec_type total_seconds() const;
tick_type total_milliseconds() const;
tick_type total_nanoseconds() const;
tick_type total_microseconds() const;
fractional_seconds_type fractional_seconds() const;
duration_type invert_sign() const;
bool is_negative() const;
booloperator<(const time_duration &) const;
booloperator==(const time_duration &) const;
duration_typeoperator-() const;
duration_typeoperator-(const duration_type &) const;
duration_typeoperator+(const duration_type &) const;
duration_typeoperator/(int) ;
duration_typeoperator-=(const duration_type &) ;
duration_typeoperator+=(const duration_type &) ;
duration_typeoperator/=(int) ;
duration_typeoperator *(int) const;
duration_typeoperator *=(int) ;
tick_type ticks() const;
bool is_special() const;
bool is_pos_infinity() const;
bool is_neg_infinity() const;
bool is_not_a_date_time() const;
impl_type get_rep() const;
// public static functionsduration_type unit() ;
tick_type ticks_per_second() ;
time_resolutions resolution() ;
unsignedshort num_fractional_digits() ;
// protected member functions
};DescriptionThis class represents a standard set of capabilities for all counted time durations. Time duration implementations should derive from this class passing their type as the first template parameter. This design allows the subclass duration types to provide custom construction policies or other custom features not provided here.<anchor id="id351182construct-copy-destruct"/><computeroutput>time_duration</computeroutput> construct/copy/destructtime_duration();time_duration(hour_type hours, min_type minutes, sec_type seconds = 0,
fractional_seconds_type frac_sec = 0);time_duration(const time_duration< T, rep_type > & other);Construct from another time_duration (Copy constructor). time_duration(special_values sv);Construct from special_values. time_duration(impl_type in);<anchor id="id389063-bb"/><computeroutput>time_duration</computeroutput> public member functionshour_typehours() const;Returns number of hours in the duration. min_typeminutes() const;Returns normalized number of minutes. sec_typeseconds() const;Returns normalized number of seconds (0..60). sec_typetotal_seconds() const;Returns total number of seconds truncating any fractional seconds. tick_typetotal_milliseconds() const;Returns total number of milliseconds truncating any fractional seconds. tick_typetotal_nanoseconds() const;Returns total number of nanoseconds truncating any sub millisecond values. tick_typetotal_microseconds() const;Returns total number of microseconds truncating any sub microsecond values. fractional_seconds_typefractional_seconds() const;Returns count of fractional seconds at given resolution. duration_typeinvert_sign() const;boolis_negative() const;booloperator<(const time_duration & rhs) const;booloperator==(const time_duration & rhs) const;duration_typeoperator-() const;unary- Allows for time_duration td = -td1 duration_typeoperator-(const duration_type & d) const;duration_typeoperator+(const duration_type & d) const;duration_typeoperator/(int divisor) ;duration_typeoperator-=(const duration_type & d) ;duration_typeoperator+=(const duration_type & d) ;duration_typeoperator/=(int divisor) ;Division operations on a duration with an integer. duration_typeoperator *(int rhs) const;Multiplication operations an a duration with an integer. duration_typeoperator *=(int divisor) ;tick_typeticks() const;boolis_special() const;Is ticks_ a special value? boolis_pos_infinity() const;Is duration pos-infinity. boolis_neg_infinity() const;Is duration neg-infinity. boolis_not_a_date_time() const;Is duration not-a-date-time. impl_typeget_rep() const;Used for special_values output. <anchor id="id414557-bb"/><computeroutput>time_duration</computeroutput> public static functionsduration_typeunit() ;Returns smallest representable duration. tick_typeticks_per_second() ;Return the number of ticks in a second. time_resolutionsresolution() ;Provide the resolution of this duration type. unsignedshortnum_fractional_digits() ;Returns number of possible digits in fractional seconds. <anchor id="id312040-bb"/><computeroutput>time_duration</computeroutput> protected member functionsClass template subsecond_duration3boost::date_time::subsecond_durationTemplate for instantiating derived adjusting durations. template<typename base_duration, long frac_of_second>
class subsecond_duration {
public:
// typestypedef base_duration::traits_type traits_type;
// construct/copy/destruct
subsecond_duration(long);
// public member functions
};Description<anchor id="subsecond_durationconstruct-copy-destruct"/><computeroutput>subsecond_duration</computeroutput> construct/copy/destructsubsecond_duration(long ss);<anchor id="id400729-bb"/><computeroutput>subsecond_duration</computeroutput> public member functionsHeader <<ulink url="../../boost/date_time/time_formatting_streams.hpp">boost/date_time/time_formatting_streams.hpp</ulink>>namespace boost {
namespace date_time {
template<typename time_duration_type, typename charT = char>
class ostream_time_duration_formatter;
template<typename time_type, typename charT = char>
class ostream_time_formatter;
template<typename time_period_type, typename charT = char>
class ostream_time_period_formatter;
}
}Class template ostream_time_duration_formatter3boost::date_time::ostream_time_duration_formatterPut a time type into a stream using appropriate facets. template<typename time_duration_type, typename charT = char>
class ostream_time_duration_formatter {
public:
// typestypedef std::basic_ostream< charT > ostream_type;
typedef time_duration_type::fractional_seconds_type fractional_seconds_type;
// public static functionsvoid duration_put(const time_duration_type &, ostream_type &) ;
};Description<anchor id="id325896-bb"/><computeroutput>ostream_time_duration_formatter</computeroutput> public static functionsvoidduration_put(const time_duration_type & td, ostream_type & os) ;Put time into an ostream. Class template ostream_time_formatter3boost::date_time::ostream_time_formatterPut a time type into a stream using appropriate facets. template<typename time_type, typename charT = char>
class ostream_time_formatter {
public:
// typestypedef std::basic_ostream< charT > ostream_type;
typedef time_type::date_type date_type;
typedef time_type::time_duration_type time_duration_type;
typedef ostream_time_duration_formatter< time_duration_type, charT > duration_formatter;
// public static functionsvoid time_put(const time_type &, ostream_type &) ;
};Description<anchor id="id303032-bb"/><computeroutput>ostream_time_formatter</computeroutput> public static functionsvoidtime_put(const time_type & t, ostream_type & os) ;Put time into an ostream. Class template ostream_time_period_formatter3boost::date_time::ostream_time_period_formatterPut a time period into a stream using appropriate facets. template<typename time_period_type, typename charT = char>
class ostream_time_period_formatter {
public:
// typestypedef std::basic_ostream< charT > ostream_type;
typedef time_period_type::point_type time_type;
typedef ostream_time_formatter< time_type, charT > time_formatter;
// public static functionsvoid period_put(const time_period_type &, ostream_type &) ;
};Description<anchor id="id423339-bb"/><computeroutput>ostream_time_period_formatter</computeroutput> public static functionsvoidperiod_put(const time_period_type & tp, ostream_type & os) ;Put time into an ostream. Header <<ulink url="../../boost/date_time/time_iterator.hpp">boost/date_time/time_iterator.hpp</ulink>>namespace boost {
namespace date_time {
template<typename time_type> class time_itr;
}
}Class template time_itr3boost::date_time::time_itrSimple time iterator skeleton class. template<typename time_type>
class time_itr {
public:
// typestypedef time_type::time_duration_type time_duration_type;
// construct/copy/destruct
time_itr(time_type, time_duration_type);
// public member functionstime_itr &operator++() ;
time_itr &operator--() ;
time_typeoperator *() ;
time_type *operator->() ;
booloperator<(const time_type &) ;
booloperator<=(const time_type &) ;
booloperator!=(const time_type &) ;
booloperator==(const time_type &) ;
booloperator>(const time_type &) ;
booloperator>=(const time_type &) ;
};Description<anchor id="time_itrconstruct-copy-destruct"/><computeroutput>time_itr</computeroutput> construct/copy/destructtime_itr(time_type t, time_duration_type d);<anchor id="id404130-bb"/><computeroutput>time_itr</computeroutput> public member functionstime_itr &operator++() ;time_itr &operator--() ;time_typeoperator *() ;time_type *operator->() ;booloperator<(const time_type & t) ;booloperator<=(const time_type & t) ;booloperator!=(const time_type & t) ;booloperator==(const time_type & t) ;booloperator>(const time_type & t) ;booloperator>=(const time_type & t) ;Header <<ulink url="../../boost/date_time/time_parsing.hpp">boost/date_time/time_parsing.hpp</ulink>>namespace boost {
namespace date_time {
template<typename time_duration>
time_duration parse_delimited_time_duration(const std::string &);
// Utility function to split appart string. boolsplit(const std::string & s, char sep, std::string & first,
std::string & second);
template<typename time_type>
time_typeparse_delimited_time(const std::string & s, char sep);
// Parse time duration part of an iso time of form: [-]hhmmss (eg: 120259 is 12 hours 2 min 59 seconds). template<typename time_duration>
time_durationparse_undelimited_time_duration(const std::string & s);
// Parse time string of form YYYYMMDDThhmmss where T is delimeter between date and time. template<typename time_type>
time_typeparse_iso_time(const std::string & s, char sep);
}
}Function template parse_delimited_time_duration3boost::date_time::parse_delimited_time_durationCreates a time_duration object from a delimited string. template<typename time_duration>
time_duration parse_delimited_time_duration(const std::string & s);DescriptionExpected format for string is "[-]h[h][:mm][:ss][.fff]". A negative duration will be created if the first character in string is a '-', all other '-' will be treated as delimiters. Accepted delimiters are "-:,.". Header <<ulink url="../../boost/date_time/time_resolution_traits.hpp">boost/date_time/time_resolution_traits.hpp</ulink>>namespace boost {
namespace date_time {
struct time_resolution_traits_bi32_impl;
struct time_resolution_traits_adapted32_impl;
struct time_resolution_traits_bi64_impl;
struct time_resolution_traits_adapted64_impl;
template<typename frac_sec_type, time_resolutions res,
#if(defined(BOOST_MSVC)&&(_MSC_VER<=1200)) boost::int64_t resolution_adjust,
#elsetypename frac_sec_type::int_type resolution_adjust,
#endif unsignedshort frac_digits,
typename v_type = boost::int32_t>
class time_resolution_traits;
typedef time_resolution_traits< time_resolution_traits_adapted32_impl, milli, 1000, 3 > milli_res;
typedef time_resolution_traits< time_resolution_traits_adapted64_impl, micro, 1000000, 6 > micro_res;
typedef time_resolution_traits< time_resolution_traits_adapted64_impl, nano, 1000000000, 9 > nano_res;
// Simple function to calculate absolute value of a numeric type. template<typename T> Tabsolute_value(T x);
}
}Struct time_resolution_traits_bi32_impl3boost::date_time::time_resolution_traits_bi32_impltraits struct for time_resolution_traits implementation type struct time_resolution_traits_bi32_impl {
// typestypedef boost::int32_t int_type;
typedef boost::int32_t impl_type;
// public static functionsint_type as_number(impl_type) ;
bool is_adapted() ;
};Description<anchor id="id409641-bb"/><computeroutput>time_resolution_traits_bi32_impl</computeroutput> public static functionsint_typeas_number(impl_type i) ;boolis_adapted() ;Used to determine if implemented type is int_adapter or int. Struct time_resolution_traits_adapted32_impl3boost::date_time::time_resolution_traits_adapted32_impltraits struct for time_resolution_traits implementation type struct time_resolution_traits_adapted32_impl {
// typestypedef boost::int32_t int_type;
typedef boost::date_time::int_adapter< boost::int32_t > impl_type;
// public static functionsint_type as_number(impl_type) ;
bool is_adapted() ;
};Description<anchor id="id341072-bb"/><computeroutput>time_resolution_traits_adapted32_impl</computeroutput> public static functionsint_typeas_number(impl_type i) ;boolis_adapted() ;Used to determine if implemented type is int_adapter or int. Struct time_resolution_traits_bi64_impl3boost::date_time::time_resolution_traits_bi64_impltraits struct for time_resolution_traits implementation type struct time_resolution_traits_bi64_impl {
// typestypedef boost::int64_t int_type;
typedef boost::int64_t impl_type;
// public static functionsint_type as_number(impl_type) ;
bool is_adapted() ;
};Description<anchor id="id407000-bb"/><computeroutput>time_resolution_traits_bi64_impl</computeroutput> public static functionsint_typeas_number(impl_type i) ;boolis_adapted() ;Used to determine if implemented type is int_adapter or int. Struct time_resolution_traits_adapted64_impl3boost::date_time::time_resolution_traits_adapted64_impltraits struct for time_resolution_traits implementation type struct time_resolution_traits_adapted64_impl {
// typestypedef boost::int64_t int_type;
typedef boost::date_time::int_adapter< boost::int64_t > impl_type;
// public static functionsint_type as_number(impl_type) ;
bool is_adapted() ;
};Description<anchor id="id408463-bb"/><computeroutput>time_resolution_traits_adapted64_impl</computeroutput> public static functionsint_typeas_number(impl_type i) ;boolis_adapted() ;Used to determine if implemented type is int_adapter or int. Class template time_resolution_traits3boost::date_time::time_resolution_traitstemplate<typename frac_sec_type, time_resolutions res,
#if(defined(BOOST_MSVC)&&(_MSC_VER<=1200)) boost::int64_t resolution_adjust,
#elsetypename frac_sec_type::int_type resolution_adjust,
#endif unsignedshort frac_digits, typename v_type = boost::int32_t>
class time_resolution_traits {
public:
// typestypedef frac_sec_type::int_type fractional_seconds_type;
typedef frac_sec_type::int_type tick_type;
typedef frac_sec_type::impl_type impl_type;
typedef v_type day_type;
typedef v_type hour_type;
typedef v_type min_type;
typedef v_type sec_type;
// public member functions BOOST_STATIC_CONSTANT(int, ticks_per_second = resolution_adjust) ;
// public static functionsfrac_sec_type::int_type as_number(typename frac_sec_type::impl_type) ;
bool is_adapted() ;
time_resolutions resolution() ;
unsignedshort num_fractional_digits() ;
fractional_seconds_type res_adjust() ;
tick_type to_tick_count(hour_type, min_type, sec_type,
fractional_seconds_type) ;
};Description<anchor id="id405643-bb"/><computeroutput>time_resolution_traits</computeroutput> public member functionsBOOST_STATIC_CONSTANT(int , ticks_per_second = resolution_adjust) ;<anchor id="id372701-bb"/><computeroutput>time_resolution_traits</computeroutput> public static functionsfrac_sec_type::int_typeas_number(typename frac_sec_type::impl_type i) ;boolis_adapted() ;time_resolutionsresolution() ;unsignedshortnum_fractional_digits() ;fractional_seconds_typeres_adjust() ;tick_typeto_tick_count(hour_type hours, min_type minutes, sec_type seconds,
fractional_seconds_type fs) ;Any negative argument results in a negative tick_count. Header <<ulink url="../../boost/date_time/time_system_counted.hpp">boost/date_time/time_system_counted.hpp</ulink>>namespace boost {
namespace date_time {
template<typename config> struct counted_time_rep;
template<typename time_rep> class counted_time_system;
}
}Struct template counted_time_rep3boost::date_time::counted_time_repTime representation that uses a single integer count. template<typename config>
struct counted_time_rep {
// typestypedef config::int_type int_type;
typedef config::date_type date_type;
typedef config::impl_type impl_type;
typedef date_type::duration_type date_duration_type;
typedef date_type::calendar_type calendar_type;
typedef date_type::ymd_type ymd_type;
typedef config::time_duration_type time_duration_type;
typedef config::resolution_traits resolution_traits;
// construct/copy/destruct
counted_time_rep(const date_type &, const time_duration_type &);
counted_time_rep(int_type);
counted_time_rep(impl_type);
// public member functionsdate_type date() const;
int_type day_count() const;
int_type time_count() const;
int_type tod() const;
bool is_pos_infinity() const;
bool is_neg_infinity() const;
bool is_not_a_date_time() const;
bool is_special() const;
impl_type get_rep() const;
// public static functionsint_type frac_sec_per_day() ;
};Description<anchor id="counted_time_repconstruct-copy-destruct"/><computeroutput>counted_time_rep</computeroutput> construct/copy/destructcounted_time_rep(const date_type & d, const time_duration_type & tod);counted_time_rep(int_type count);counted_time_rep(impl_type count);<anchor id="id427696-bb"/><computeroutput>counted_time_rep</computeroutput> public member functionsdate_typedate() const;int_typeday_count() const;int_typetime_count() const;int_typetod() const;boolis_pos_infinity() const;boolis_neg_infinity() const;boolis_not_a_date_time() const;boolis_special() const;impl_typeget_rep() const;<anchor id="id353151-bb"/><computeroutput>counted_time_rep</computeroutput> public static functionsint_typefrac_sec_per_day() ;Class template counted_time_system3boost::date_time::counted_time_systemAn unadjusted time system implementation. template<typename time_rep>
class counted_time_system {
public:
// typestypedef time_rep time_rep_type;
typedef time_rep_type::impl_type impl_type;
typedef time_rep_type::time_duration_type time_duration_type;
typedef time_duration_type::fractional_seconds_type fractional_seconds_type;
typedef time_rep_type::date_type date_type;
typedef time_rep_type::date_duration_type date_duration_type;
// public static functionstemplate<typename T> void unused_var(const T &) ;
time_rep_type
get_time_rep(const date_type &, const time_duration_type &,
date_time::dst_flags = not_dst) ;
date_type get_date(const time_rep_type &) ;
time_duration_type get_time_of_day(const time_rep_type &) ;
std::string zone_name(const time_rep_type &) ;
bool is_equal(const time_rep_type &, const time_rep_type &) ;
bool is_less(const time_rep_type &, const time_rep_type &) ;
time_rep_type add_days(const time_rep_type &, const date_duration_type &) ;
time_rep_type
subtract_days(const time_rep_type &, const date_duration_type &) ;
time_rep_type
subtract_time_duration(const time_rep_type &, const time_duration_type &) ;
time_rep_type add_time_duration(const time_rep_type &, time_duration_type) ;
time_duration_type
subtract_times(const time_rep_type &, const time_rep_type &) ;
};Description<anchor id="id426276-bb"/><computeroutput>counted_time_system</computeroutput> public static functionstemplate<typename T> voidunused_var(const T & ) ;time_rep_typeget_time_rep(const date_type & day, const time_duration_type & tod,
date_time::dst_flags dst = not_dst) ;date_typeget_date(const time_rep_type & val) ;time_duration_typeget_time_of_day(const time_rep_type & val) ;std::stringzone_name(const time_rep_type & ) ;boolis_equal(const time_rep_type & lhs, const time_rep_type & rhs) ;boolis_less(const time_rep_type & lhs, const time_rep_type & rhs) ;time_rep_typeadd_days(const time_rep_type & base, const date_duration_type & dd) ;time_rep_typesubtract_days(const time_rep_type & base, const date_duration_type & dd) ;time_rep_typesubtract_time_duration(const time_rep_type & base,
const time_duration_type & td) ;time_rep_typeadd_time_duration(const time_rep_type & base, time_duration_type td) ;time_duration_typesubtract_times(const time_rep_type & lhs, const time_rep_type & rhs) ;Header <<ulink url="../../boost/date_time/time_system_split.hpp">boost/date_time/time_system_split.hpp</ulink>>namespace boost {
namespace date_time {
template<typename config, boost::int32_t ticks_per_second>
class split_timedate_system;
}
}Class template split_timedate_system3boost::date_time::split_timedate_systemAn unadjusted time system implementation. template<typename config, boost::int32_t ticks_per_second>
class split_timedate_system {
public:
// typestypedef config::time_rep_type time_rep_type;
typedef config::date_type date_type;
typedef config::time_duration_type time_duration_type;
typedef config::date_duration_type date_duration_type;
typedef config::int_type int_type;
typedef config::resolution_traits resolution_traits;
typedef date_time::wrapping_int< int_type, INT64_C(86400)*ticks_per_second wrap_int_type;
typedef date_time::wrapping_int< int_type, ticks_per_day > wrap_int_type;
// public static functionstime_rep_type
get_time_rep(const date_type &, const time_duration_type &,
date_time::dst_flags = not_dst) ;
date_type get_date(const time_rep_type &) ;
time_duration_type get_time_of_day(const time_rep_type &) ;
std::string zone_name(const time_rep_type &) ;
bool is_equal(const time_rep_type &, const time_rep_type &) ;
bool is_less(const time_rep_type &, const time_rep_type &) ;
time_rep_type add_days(const time_rep_type &, const date_duration_type &) ;
time_rep_type
subtract_days(const time_rep_type &, const date_duration_type &) ;
time_rep_type
subtract_time_duration(const time_rep_type &, const time_duration_type &) ;
time_rep_type add_time_duration(const time_rep_type &, time_duration_type) ;
time_duration_type
subtract_times(const time_rep_type &, const time_rep_type &) ;
// private member functions BOOST_STATIC_CONSTANT(int_type,
ticks_per_day = INT64_C(86400)*config::tick_per_second) ;
};Description<anchor id="id309506-bb"/><computeroutput>split_timedate_system</computeroutput> public static functionstime_rep_typeget_time_rep(const date_type & day, const time_duration_type & tod,
date_time::dst_flags dst = not_dst) ;date_typeget_date(const time_rep_type & val) ;time_duration_typeget_time_of_day(const time_rep_type & val) ;std::stringzone_name(const time_rep_type & ) ;boolis_equal(const time_rep_type & lhs, const time_rep_type & rhs) ;boolis_less(const time_rep_type & lhs, const time_rep_type & rhs) ;time_rep_typeadd_days(const time_rep_type & base, const date_duration_type & dd) ;time_rep_typesubtract_days(const time_rep_type & base, const date_duration_type & dd) ;time_rep_typesubtract_time_duration(const time_rep_type & base,
const time_duration_type & td) ;time_rep_typeadd_time_duration(const time_rep_type & base, time_duration_type td) ;time_duration_typesubtract_times(const time_rep_type & lhs, const time_rep_type & rhs) ;<anchor id="id352903-bb"/><computeroutput>split_timedate_system</computeroutput> private member functionsBOOST_STATIC_CONSTANT(int_type ,
ticks_per_day = INT64_C(86400)*config::tick_per_second) ;Header <<ulink url="../../boost/date_time/wrapping_int.hpp">boost/date_time/wrapping_int.hpp</ulink>>namespace boost {
namespace date_time {
template<typename int_type_, int_type_ wrap_val> class wrapping_int;
template<typename int_type_, int_type_ wrap_min, int_type_ wrap_max>
class wrapping_int2;
}
}Class template wrapping_int3boost::date_time::wrapping_intA wrapping integer used to support time durations. template<typename int_type_, int_type_ wrap_val>
class wrapping_int {
public:
// typestypedef int_type_ int_type;
// construct/copy/destruct
wrapping_int(int_type);
// public member functionsint_type as_int() const;
operator int_type() const;
int_type add(int_type) ;
int_type subtract(int_type) ;
// public static functionsint_type wrap_value() ;
};DescriptionIn composite date and time types this type is used to wrap at the day boundary. <anchor id="wrapping_intconstruct-copy-destruct"/><computeroutput>wrapping_int</computeroutput> construct/copy/destructwrapping_int(int_type v);Add, return true if wrapped. <anchor id="id318942-bb"/><computeroutput>wrapping_int</computeroutput> public member functionsint_typeas_int() const;Explicit converion method. operator int_type() const;int_typeadd(int_type v) ;int_typesubtract(int_type v) ;<anchor id="id433467-bb"/><computeroutput>wrapping_int</computeroutput> public static functionsint_typewrap_value() ;Class template wrapping_int23boost::date_time::wrapping_int2A wrapping integer used to wrap around at the top. template<typename int_type_, int_type_ wrap_min, int_type_ wrap_max>
class wrapping_int2 {
public:
// typestypedef int_type_ int_type;
// construct/copy/destruct
wrapping_int2(int_type);
// public member functionsint_type as_int() const;
operator int_type() const;
int_type add(int_type) ;
int_type subtract(int_type) ;
// public static functionsunsignedlong wrap_value() ;
unsignedlong min_value() ;
};DescriptionBad name, quick impl to fix a bug -- fix later!! This allows the wrap to restart at a value other than 0. Currently this only works if wrap_min == 1 <anchor id="wrapping_int2construct-copy-destruct"/><computeroutput>wrapping_int2</computeroutput> construct/copy/destructwrapping_int2(int_type v);If initializing value is out of range of [wrap_min, wrap_max], value will be initialized to closest of min or max <anchor id="id374620-bb"/><computeroutput>wrapping_int2</computeroutput> public member functionsint_typeas_int() const;Explicit converion method. operator int_type() const;int_typeadd(int_type v) ;Add, return number of wraps performed. int_typesubtract(int_type v) ;Subtract will return '-d' if wrapping took place ('d' is the number of wraps). <anchor id="id392564-bb"/><computeroutput>wrapping_int2</computeroutput> public static functionsunsignedlongwrap_value() ;unsignedlongmin_value() ;Header <<ulink url="../../boost/date_time/year_month_day.hpp">boost/date_time/year_month_day.hpp</ulink>>namespace boost {
namespace date_time {
template<typename YearType, typename MonthType, typename DayType>
struct year_month_day_base;
}
}Struct template year_month_day_base3boost::date_time::year_month_day_baseAllow rapid creation of ymd triples of different types. template<typename YearType, typename MonthType, typename DayType>
struct year_month_day_base {
// typestypedef YearType year_type;
typedef MonthType month_type;
typedef DayType day_type;
// construct/copy/destruct
year_month_day_base(YearType, MonthType, DayType);
// public member functions
YearType year;
MonthType month;
DayType day;
};Description<anchor id="year_month_day_baseconstruct-copy-destruct"/><computeroutput>year_month_day_base</computeroutput> construct/copy/destructyear_month_day_base(YearType year, MonthType month, DayType day);A basic constructor. <anchor id="id288033-bb"/><computeroutput>year_month_day_base</computeroutput> public member functionsGregorian ReferenceHeader <<ulink url="../../boost/date_time/gregorian/formatters.hpp">boost/date_time/gregorian/formatters.hpp</ulink>>namespace boost {
namespace gregorian {
template<typename charT>
std::basic_string< charT >to_simple_string_type(const date & d);
// To YYYY-mmm-DD string where mmm 3 char month name. Example: 2002-Jan-01. std::stringto_simple_string(const date & d);
template<typename charT>
std::basic_string< charT >to_simple_string_type(const date_period & d);
// Convert date period to simple string. Example: [2002-Jan-01/2002-Jan-02]. std::stringto_simple_string(const date_period & d);
template<typename charT>
std::basic_string< charT >to_iso_string_type(const date_period & d);
// Date period to iso standard format CCYYMMDD/CCYYMMDD. Example: 20021225/20021231. std::stringto_iso_string(const date_period & d);
template<typename charT>
std::basic_string< charT >to_iso_extended_string_type(const date & d);
// Convert to iso extended format string CCYY-MM-DD. Example 2002-12-31. std::stringto_iso_extended_string(const date & d);
template<typename charT>
std::basic_string< charT >to_iso_string_type(const date & d);
// Convert to iso standard string YYYYMMDD. Example: 20021231. std::stringto_iso_string(const date & d);
template<typename charT>
std::basic_string< charT >to_sql_string_type(const date & d);
std::stringto_sql_string(const date & d);
// Convert date period to simple string. Example: [2002-Jan-01/2002-Jan-02]. std::wstringto_simple_wstring(const date_period & d);
// To YYYY-mmm-DD string where mmm 3 char month name. Example: 2002-Jan-01. std::wstringto_simple_wstring(const date & d);
// Date period to iso standard format CCYYMMDD/CCYYMMDD. Example: 20021225/20021231. std::wstringto_iso_wstring(const date_period & d);
// Convert to iso extended format string CCYY-MM-DD. Example 2002-12-31. std::wstringto_iso_extended_wstring(const date & d);
// Convert to iso standard string YYYYMMDD. Example: 20021231. std::wstringto_iso_wstring(const date & d);
std::wstringto_sql_wstring(const date & d);
}
}Header <<ulink url="../../boost/date_time/gregorian/formatters_limited.hpp">boost/date_time/gregorian/formatters_limited.hpp</ulink>>namespace boost {
namespace gregorian {
}
}Header <<ulink url="../../boost/date_time/gregorian/greg_calendar.hpp">boost/date_time/gregorian/greg_calendar.hpp</ulink>>namespace boost {
namespace gregorian {
class gregorian_calendar;
typedef date_time::int_adapter< unsignedlong > fancy_date_rep; // An internal date representation that includes infinities, not a date.
}
}Class gregorian_calendar3boost::gregorian::gregorian_calendarGregorian calendar for this implementation, hard work in the base. class gregorian_calendar {
public:
// typestypedef greg_weekday day_of_week_type; // Type to hold a weekday (eg: Sunday, Monday,...). typedef greg_day_of_year_rep day_of_year_type; // Counter type from 1 to 366 for gregorian dates. typedef fancy_date_rep date_rep_type; // Internal date representation that handles infinity, not a date. typedef fancy_date_rep date_traits_type; // Date rep implements the traits stuff as well.
};Header <<ulink url="../../boost/date_time/gregorian/greg_date.hpp">boost/date_time/gregorian/greg_date.hpp</ulink>>namespace boost {
namespace gregorian {
class date;
}
}Class date3boost::gregorian::dateA date type based on gregorian_calendar. class date {
public:
// typestypedef gregorian_calendar::year_type year_type;
typedef gregorian_calendar::month_type month_type;
typedef gregorian_calendar::day_type day_type;
typedef gregorian_calendar::day_of_year_type day_of_year_type;
typedef gregorian_calendar::ymd_type ymd_type;
typedef gregorian_calendar::date_rep_type date_rep_type;
typedef gregorian_calendar::date_int_type date_int_type;
typedef date_duration duration_type;
// construct/copy/destruct
date();
date(year_type, month_type, day_type);
date(const ymd_type &);
date(const date_int_type &);
date(date_rep_type);
date(special_values);
// public member functionsdate_int_type julian_day() const;
day_of_year_type day_of_year() const;
long modjulian_day() const;
int week_number() const;
date_int_type day_number() const;
};DescriptionThis class is the primary interface for programming with greogorian dates. The is a lightweight type that can be freely passed by value. All comparison operators are supported. <anchor id="boost.gregorian.dateconstruct-copy-destruct"/><computeroutput>date</computeroutput> construct/copy/destructdate();Default constructor constructs with not_a_date_time. date(year_type y, month_type m, day_type d);Main constructor with year, month, day. date(const ymd_type & ymd);Constructor from a ymd_type structure. date(const date_int_type & rhs);Needed copy constructor. date(date_rep_type rhs);Needed copy constructor. date(special_values sv);Constructor for infinities, not a date, max and min date. <anchor id="id383784-bb"/><computeroutput>date</computeroutput> public member functionsdate_int_typejulian_day() const;Return the Julian Day number for the date. day_of_year_typeday_of_year() const;Return the day of year 1..365 or 1..366 (for leap year). longmodjulian_day() const;Return the Modified Julian Day number for the date. intweek_number() const;Return the iso 8601 week number 1..53. date_int_typeday_number() const;Return the day number from the calendar. Header <<ulink url="../../boost/date_time/gregorian/greg_day.hpp">boost/date_time/gregorian/greg_day.hpp</ulink>>namespace boost {
namespace gregorian {
struct bad_day_of_month;
class greg_day;
typedef CV::simple_exception_policy< unsignedshort, 1, 31, bad_day_of_month > greg_day_policies; // Policy class that declares error handling and day of month ranges. typedef CV::constrained_value< greg_day_policies > greg_day_rep; // Generated represetation for gregorian day of month.
}
}Struct bad_day_of_month3boost::gregorian::bad_day_of_monthException type for gregorian day of month (1..31). struct bad_day_of_month {
// construct/copy/destruct
bad_day_of_month();
bad_day_of_month(const std::string &);
// public member functions
};Description<anchor id="bad_day_of_monthconstruct-copy-destruct"/><computeroutput>bad_day_of_month</computeroutput> construct/copy/destructbad_day_of_month();bad_day_of_month(const std::string & s);Allow other classes to throw with unique string for bad day like Feb 29. <anchor id="id324139-bb"/><computeroutput>bad_day_of_month</computeroutput> public member functionsClass greg_day3boost::gregorian::greg_dayRepresent a day of the month (range 1 - 31). class greg_day {
public:
// construct/copy/destruct
greg_day(unsignedshort);
// public member functionsunsignedshort as_number() const;
operatorunsignedshort() const;
};DescriptionThis small class allows for simple conversion an integer value into a day of the month for a standard gregorian calendar. The type is automatically range checked so values outside of the range 1-31 will cause a bad_day_of_month exception <anchor id="greg_dayconstruct-copy-destruct"/><computeroutput>greg_day</computeroutput> construct/copy/destructgreg_day(unsignedshort day_of_month);<anchor id="id382216-bb"/><computeroutput>greg_day</computeroutput> public member functionsunsignedshortas_number() const;operatorunsignedshort() const;Header <<ulink url="../../boost/date_time/gregorian/greg_day_of_year.hpp">boost/date_time/gregorian/greg_day_of_year.hpp</ulink>>namespace boost {
namespace gregorian {
struct bad_day_of_year;
typedef CV::simple_exception_policy< unsignedshort, 1, 366, bad_day_of_year > greg_day_of_year_policies; // A day of the year range (1..366). typedef CV::constrained_value< greg_day_of_year_policies > greg_day_of_year_rep; // Define a range representation type for the day of the year 1..366.
}
}Struct bad_day_of_year3boost::gregorian::bad_day_of_yearException type for day of year (1..366). struct bad_day_of_year {
// construct/copy/destruct
bad_day_of_year();
// public member functions
};Description<anchor id="bad_day_of_yearconstruct-copy-destruct"/><computeroutput>bad_day_of_year</computeroutput> construct/copy/destructbad_day_of_year();<anchor id="id425177-bb"/><computeroutput>bad_day_of_year</computeroutput> public member functionsHeader <<ulink url="../../boost/date_time/gregorian/greg_duration.hpp">boost/date_time/gregorian/greg_duration.hpp</ulink>>namespace boost {
namespace gregorian {
typedef boost::date_time::duration_traits_adapted date_duration_rep; // An internal date representation that includes infinities, not a date. typedef date_time::date_duration< date_duration_rep > date_duration; // Durations in days for gregorian system. typedef date_duration days; // Shorthand for date_duration.
}
}Header <<ulink url="../../boost/date_time/gregorian/greg_duration_types.hpp">boost/date_time/gregorian/greg_duration_types.hpp</ulink>>namespace boost {
namespace gregorian {
struct greg_durations_config;
typedef date_time::months_duration< greg_durations_config > months;
typedef date_time::years_duration< greg_durations_config > years;
typedef date_time::weeks_duration< date_time::duration_traits_adapted > weeks;
}
}Struct greg_durations_config3boost::gregorian::greg_durations_configconfig struct for additional duration types (ie months_duration<> & years_duration<>) struct greg_durations_config {
// typestypedef date date_type;
typedef date_time::int_adapter< int > int_rep;
typedef date_time::month_functor< date_type > month_adjustor_type;
};Header <<ulink url="../../boost/date_time/gregorian/greg_facet.hpp">boost/date_time/gregorian/greg_facet.hpp</ulink>>namespace boost {
namespace gregorian {
struct greg_facet_config;
typedef boost::date_time::date_names_put< greg_facet_config > greg_base_facet; // Create the base facet type for gregorian::date. template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > &, const date &);
template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > &, const greg_month &);
template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > &, const greg_weekday &);
template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > &, const date_period &);
template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os,
const date_duration & dd);
// operator<< for gregorian::partial_date. Output: "Jan 1" template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os,
const partial_date & pd);
// operator<< for gregorian::nth_kday_of_month. Output: "first Mon of Jun" template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os,
const nth_kday_of_month & nkd);
// operator<< for gregorian::first_kday_of_month. Output: "first Mon of Jun" template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os,
const first_kday_of_month & fkd);
// operator<< for gregorian::last_kday_of_month. Output: "last Mon of Jun" template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os,
const last_kday_of_month & lkd);
// operator<< for gregorian::first_kday_after. Output: "first Mon after" template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os,
const first_kday_after & fka);
// operator<< for gregorian::first_kday_before. Output: "first Mon before" template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os,
const first_kday_before & fkb);
// operator>> for gregorian::date template<typename charT>
std::basic_istream< charT > &operator>>(std::basic_istream< charT > & is, date & d);
// operator>> for gregorian::date_duration template<typename charT>
std::basic_istream< charT > &operator>>(std::basic_istream< charT > & is, date_duration & dd);
// operator>> for gregorian::date_period template<typename charT>
std::basic_istream< charT > &operator>>(std::basic_istream< charT > & is, date_period & dp);
// generates a locale with the set of gregorian name-strings of type char* BOOST_DATE_TIME_DECL std::localegenerate_locale(std::locale & loc, char type);
// Returns a pointer to a facet with a default set of names (English). BOOST_DATE_TIME_DECL boost::date_time::all_date_names_put< greg_facet_config, char > *create_facet_def(char type);
// generates a locale with the set of gregorian name-strings of type wchar_t* BOOST_DATE_TIME_DECL std::localegenerate_locale(std::locale & loc, wchar_t type);
// Returns a pointer to a facet with a default set of names (English). BOOST_DATE_TIME_DECL boost::date_time::all_date_names_put< greg_facet_config, wchar_t > *create_facet_def(wchar_t type);
// operator>> for gregorian::greg_month - throws exception if invalid month given template<typename charT>
std::basic_istream< charT > &operator>>(std::basic_istream< charT > & is, greg_month & m);
// operator>> for gregorian::greg_weekday - throws exception if invalid weekday given template<typename charT>
std::basic_istream< charT > &operator>>(std::basic_istream< charT > & is, greg_weekday & wd);
}
}Struct greg_facet_config3boost::gregorian::greg_facet_configConfiguration of the output facet template. struct greg_facet_config {
// typestypedef boost::gregorian::greg_month month_type;
typedef boost::date_time::special_values special_value_enum;
typedef boost::gregorian::months_of_year month_enum;
typedef boost::date_time::weekdays weekday_enum;
};Function template operator<<3boost::gregorian::operator<<ostream operator for gregorian::date template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os, const date & d);DescriptionUses the date facet to determine various output parameters including:string values for the month (eg: Jan, Feb, Mar) (default: English)string values for special values (eg: not-a-date-time) (default: English)selection of long, short strings, or numerical month representation (default: short string)month day year order (default yyyy-mmm-dd) Function template operator<<3boost::gregorian::operator<<operator<< for gregorian::greg_month typically streaming: Jan, Feb, Mar... template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os, const greg_month & m);DescriptionUses the date facet to determine output string as well as selection of long or short strings. Default if no facet is installed is to output a 2 wide numeric value for the month eg: 01 == Jan, 02 == Feb, ... 12 == Dec. Function template operator<<3boost::gregorian::operator<<operator<< for gregorian::greg_weekday typically streaming: Sun, Mon, Tue, ... template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os,
const greg_weekday & wd);DescriptionUses the date facet to determine output string as well as selection of long or short string. Default if no facet is installed is to output a 3 char english string for the day of the week. Function template operator<<3boost::gregorian::operator<<operator<< for gregorian::date_period typical output: [2002-Jan-01/2002-Jan-31] template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os, const date_period & dp);DescriptionUses the date facet to determine output string as well as selection of long or short string fr dates. Default if no facet is installed is to output a 3 char english string for the day of the week. Header <<ulink url="../../boost/date_time/gregorian/greg_month.hpp">boost/date_time/gregorian/greg_month.hpp</ulink>>namespace boost {
namespace gregorian {
struct bad_month;
class greg_month;
typedef date_time::months_of_year months_of_year;
typedef CV::simple_exception_policy< unsignedshort, 1, 12, bad_month > greg_month_policies; // Build a policy class for the greg_month_rep. typedef CV::constrained_value< greg_month_policies > greg_month_rep; // A constrained range that implements the gregorian_month rules.
}
}Struct bad_month3boost::gregorian::bad_monthException thrown if a greg_month is constructed with a value out of range. struct bad_month {
// construct/copy/destruct
bad_month();
// public member functions
};Description<anchor id="bad_monthconstruct-copy-destruct"/><computeroutput>bad_month</computeroutput> construct/copy/destructbad_month();<anchor id="id363940-bb"/><computeroutput>bad_month</computeroutput> public member functionsClass greg_month3boost::gregorian::greg_monthWrapper class to represent months in gregorian based calendar. class greg_month {
public:
// typestypedef date_time::months_of_year month_enum;
typedef std::map< std::string, unsignedshort > month_map_type;
typedef boost::shared_ptr< month_map_type > month_map_ptr_type;
// construct/copy/destruct
greg_month(month_enum);
greg_month(unsignedshort);
// public member functionsoperatorunsignedshort() const;
unsignedshort as_number() const;
month_enum as_enum() const;
constchar * as_short_string() const;
constchar * as_long_string() const;
constwchar_t * as_short_wstring() const;
constwchar_t * as_long_wstring() const;
constchar * as_short_string(char) const;
constchar * as_long_string(char) const;
constwchar_t * as_short_string(wchar_t) const;
constwchar_t * as_long_string(wchar_t) const;
// public static functionsmonth_map_ptr_type get_month_map_ptr() ;
};Description<anchor id="greg_monthconstruct-copy-destruct"/><computeroutput>greg_month</computeroutput> construct/copy/destructgreg_month(month_enum theMonth);Construct a month from the months_of_year enumeration. greg_month(unsignedshort theMonth);Construct from a short value. <anchor id="id309901-bb"/><computeroutput>greg_month</computeroutput> public member functionsoperatorunsignedshort() const;Convert the value back to a short. unsignedshortas_number() const;Returns month as number from 1 to 12. month_enumas_enum() const;constchar *as_short_string() const;constchar *as_long_string() const;constwchar_t *as_short_wstring() const;constwchar_t *as_long_wstring() const;constchar *as_short_string(char ) const;constchar *as_long_string(char ) const;constwchar_t *as_short_string(wchar_t ) const;constwchar_t *as_long_string(wchar_t ) const;<anchor id="id229966-bb"/><computeroutput>greg_month</computeroutput> public static functionsmonth_map_ptr_typeget_month_map_ptr() ;Shared pointer to a map of Month strings (Names & Abbrev) & numbers. Header <<ulink url="../../boost/date_time/gregorian/greg_weekday.hpp">boost/date_time/gregorian/greg_weekday.hpp</ulink>>namespace boost {
namespace gregorian {
struct bad_weekday;
class greg_weekday;
typedef CV::simple_exception_policy< unsignedshort, 0, 6, bad_weekday > greg_weekday_policies;
typedef CV::constrained_value< greg_weekday_policies > greg_weekday_rep;
}
}Struct bad_weekday3boost::gregorian::bad_weekdayException that flags that a weekday number is incorrect. struct bad_weekday {
// construct/copy/destruct
bad_weekday();
// public member functions
};Description<anchor id="bad_weekdayconstruct-copy-destruct"/><computeroutput>bad_weekday</computeroutput> construct/copy/destructbad_weekday();<anchor id="id389085-bb"/><computeroutput>bad_weekday</computeroutput> public member functionsClass greg_weekday3boost::gregorian::greg_weekdayRepresent a day within a week (range 0==Sun to 6==Sat). class greg_weekday {
public:
// typestypedef boost::date_time::weekdays weekday_enum;
// construct/copy/destruct
greg_weekday(unsignedshort);
// public member functionsunsignedshort as_number() const;
constchar * as_short_string() const;
constchar * as_long_string() const;
constwchar_t * as_short_wstring() const;
constwchar_t * as_long_wstring() const;
weekday_enum as_enum() const;
};Description<anchor id="greg_weekdayconstruct-copy-destruct"/><computeroutput>greg_weekday</computeroutput> construct/copy/destructgreg_weekday(unsignedshort day_of_week_num);<anchor id="id368644-bb"/><computeroutput>greg_weekday</computeroutput> public member functionsunsignedshortas_number() const;constchar *as_short_string() const;constchar *as_long_string() const;constwchar_t *as_short_wstring() const;constwchar_t *as_long_wstring() const;weekday_enumas_enum() const;Header <<ulink url="../../boost/date_time/gregorian/greg_year.hpp">boost/date_time/gregorian/greg_year.hpp</ulink>>namespace boost {
namespace gregorian {
struct bad_year;
class greg_year;
typedef CV::simple_exception_policy< unsignedshort, 1400, 10000, bad_year > greg_year_policies; // Policy class that declares error handling gregorian year type. typedef CV::constrained_value< greg_year_policies > greg_year_rep; // Generated representation for gregorian year.
}
}Struct bad_year3boost::gregorian::bad_yearException type for gregorian year. struct bad_year {
// construct/copy/destruct
bad_year();
// public member functions
};Description<anchor id="bad_yearconstruct-copy-destruct"/><computeroutput>bad_year</computeroutput> construct/copy/destructbad_year();<anchor id="id398137-bb"/><computeroutput>bad_year</computeroutput> public member functionsClass greg_year3boost::gregorian::greg_yearRepresent a day of the month (range 1900 - 10000). class greg_year {
public:
// construct/copy/destruct
greg_year(unsignedshort);
// public member functionsoperatorunsignedshort() const;
};DescriptionThis small class allows for simple conversion an integer value into a year for the gregorian calendar. This currently only allows a range of 1900 to 10000. Both ends of the range are a bit arbitrary at the moment, but they are the limits of current testing of the library. As such they may be increased in the future. <anchor id="greg_yearconstruct-copy-destruct"/><computeroutput>greg_year</computeroutput> construct/copy/destructgreg_year(unsignedshort year);<anchor id="id325863-bb"/><computeroutput>greg_year</computeroutput> public member functionsoperatorunsignedshort() const;Header <<ulink url="../../boost/date_time/gregorian/greg_ymd.hpp">boost/date_time/gregorian/greg_ymd.hpp</ulink>>namespace boost {
namespace gregorian {
typedef date_time::year_month_day_base< greg_year, greg_month, greg_day > greg_year_month_day;
}
}Header <<ulink url="../../boost/date_time/gregorian/gregorian.hpp">boost/date_time/gregorian/gregorian.hpp</ulink>>Single file header that provides overall include for all elements of the gregorian date-time system. This includes the various types defined, but also other functions for formatting and parsing.Header <<ulink url="../../boost/date_time/gregorian/gregorian_types.hpp">boost/date_time/gregorian/gregorian_types.hpp</ulink>>Single file header that defines most of the types for the gregorian date-time system.namespace boost {
namespace gregorian {
typedef date_time::period< date, date_duration > date_period; // Date periods for the gregorian system. typedef date_time::year_based_generator< date > year_based_generator; // A unifying date_generator base type. typedef date_time::partial_date< date > partial_date; // A date generation object type. typedef date_time::nth_kday_of_month< date > nth_kday_of_month;
typedef nth_kday_of_month nth_day_of_the_week_in_month;
typedef date_time::first_kday_of_month< date > first_kday_of_month;
typedef first_kday_of_month first_day_of_the_week_in_month;
typedef date_time::last_kday_of_month< date > last_kday_of_month;
typedef last_kday_of_month last_day_of_the_week_in_month;
typedef date_time::first_kday_after< date > first_kday_after;
typedef first_kday_after first_day_of_the_week_after;
typedef date_time::first_kday_before< date > first_kday_before;
typedef first_kday_before first_day_of_the_week_before;
typedef date_time::day_clock< date > day_clock; // A clock to get the current day from the local computer. typedef date_time::date_itr_base< date > date_iterator; // Base date_iterator type for gregorian types. typedef date_time::date_itr< date_time::day_functor< date >, date > day_iterator; // A day level iterator. typedef date_time::date_itr< date_time::week_functor< date >, date > week_iterator; // A week level iterator. typedef date_time::date_itr< date_time::month_functor< date >, date > month_iterator; // A month level iterator. typedef date_time::date_itr< date_time::year_functor< date >, date > year_iterator; // A year level iterator.
}
}Header <<ulink url="../../boost/date_time/gregorian/parsers.hpp">boost/date_time/gregorian/parsers.hpp</ulink>>namespace boost {
namespace gregorian {
// Deprecated: Use from_simple_string. datefrom_string(std::string s);
// From delimited date string where with order year-month-day eg: 2002-1-25 or 2003-Jan-25 (full month name is also accepted). datefrom_simple_string(std::string s);
// From delimited date string where with order year-month-day eg: 1-25-2003 or Jan-25-2003 (full month name is also accepted). datefrom_us_string(std::string s);
// From delimited date string where with order day-month-year eg: 25-1-2002 or 25-Jan-2003 (full month name is also accepted). datefrom_uk_string(std::string s);
// From iso type date string where with order year-month-day eg: 20020125. datefrom_undelimited_string(std::string s);
// From iso type date string where with order year-month-day eg: 20020125. datedate_from_iso_string(const std::string & s);
// Stream should hold a date in the form of: 2002-1-25. Month number, abbrev, or name are accepted. template<typename iterator_type>
datefrom_stream(iterator_type beg, iterator_type end);
// Function to parse a date_period from a string (eg: [2003-Oct-31/2003-Dec-25]). date_perioddate_period_from_string(const std::string & s);
// Function to parse a date_period from a wstring (eg: [2003-Oct-31/2003-Dec-25]). date_perioddate_period_from_wstring(const std::wstring & s);
}
}Posix Time ReferenceHeader <<ulink url="../../boost/date_time/posix_time/conversion.hpp">boost/date_time/posix_time/conversion.hpp</ulink>>namespace boost {
namespace posix_time {
// Function that converts a time_t into a ptime. ptimefrom_time_t(std::time_t t);
template<typename time_type> time_type from_ftime(const FILETIME &);
}
}Function template from_ftime3boost::posix_time::from_ftimeFunction to create a time object from an initialized FILETIME struct. template<typename time_type> time_type from_ftime(const FILETIME & ft);DescriptionFunction to create a time object from an initialized FILETIME struct. A FILETIME struct holds 100-nanosecond units (0.0000001). When built with microsecond resolution the FILETIME's sub second value will be truncated. Nanosecond resolution has no truncation.Note ftime is part of the Win32 API, so it is not portable to non-windows platforms. Header <<ulink url="../../boost/date_time/posix_time/date_duration_operators.hpp">boost/date_time/posix_time/date_duration_operators.hpp</ulink>>Operators for ptime and optional gregorian types. Operators use snap-to-end-of-month behavior. Further details on this behavior can be found in reference for date_time/date_duration_types.hpp and documentation for month and year iterators.namespace boost {
namespace posix_time {
ptimeoperator+(const ptime &, const boost::gregorian::months &);
ptimeoperator+=(ptime &, const boost::gregorian::months &);
ptimeoperator-(const ptime &, const boost::gregorian::months &);
ptimeoperator-=(ptime &, const boost::gregorian::months &);
ptimeoperator+(const ptime &, const boost::gregorian::years &);
ptimeoperator+=(ptime &, const boost::gregorian::years &);
ptimeoperator-(const ptime &, const boost::gregorian::years &);
ptimeoperator-=(ptime &, const boost::gregorian::years &);
}
}Function operator+3boost::posix_time::operator+ptimeoperator+(const ptime & t, const boost::gregorian::months & m);DescriptionAdds a months object and a ptime. Result will be same day-of-month as ptime unless original day was the last day of month. see date_time::months_duration for more details Function operator+=3boost::posix_time::operator+=ptimeoperator+=(ptime & t, const boost::gregorian::months & m);DescriptionAdds a months object to a ptime. Result will be same day-of-month as ptime unless original day was the last day of month. see date_time::months_duration for more details Function operator-3boost::posix_time::operator-ptimeoperator-(const ptime & t, const boost::gregorian::months & m);DescriptionSubtracts a months object and a ptime. Result will be same day-of-month as ptime unless original day was the last day of month. see date_time::months_duration for more details Function operator-=3boost::posix_time::operator-=ptimeoperator-=(ptime & t, const boost::gregorian::months & m);DescriptionSubtracts a months object from a ptime. Result will be same day-of-month as ptime unless original day was the last day of month. see date_time::months_duration for more details Function operator+3boost::posix_time::operator+ptimeoperator+(const ptime & t, const boost::gregorian::years & y);DescriptionAdds a years object and a ptime. Result will be same month and day-of-month as ptime unless original day was the last day of month. see date_time::years_duration for more details Function operator+=3boost::posix_time::operator+=ptimeoperator+=(ptime & t, const boost::gregorian::years & y);DescriptionAdds a years object to a ptime. Result will be same month and day-of-month as ptime unless original day was the last day of month. see date_time::years_duration for more details Function operator-3boost::posix_time::operator-ptimeoperator-(const ptime & t, const boost::gregorian::years & y);DescriptionSubtracts a years object and a ptime. Result will be same month and day-of-month as ptime unless original day was the last day of month. see date_time::years_duration for more details Function operator-=3boost::posix_time::operator-=ptimeoperator-=(ptime & t, const boost::gregorian::years & y);DescriptionSubtracts a years object from a ptime. Result will be same month and day-of-month as ptime unless original day was the last day of month. see date_time::years_duration for more details Header <<ulink url="../../boost/date_time/posix_time/posix_time.hpp">boost/date_time/posix_time/posix_time.hpp</ulink>>Global header file to get all of posix time typesHeader <<ulink url="../../boost/date_time/posix_time/posix_time_config.hpp">boost/date_time/posix_time/posix_time_config.hpp</ulink>>namespace boost {
namespace posix_time {
class time_duration;
struct simple_time_rep;
class posix_time_system_config;
class millisec_posix_time_system_config;
typedef date_time::time_resolution_traits< boost::date_time::time_resolution_traits_adapted64_impl, boost::date_time::nano, 1000000000, 9 > time_res_traits;
}
}Class time_duration3boost::posix_time::time_durationBase time duration type. class time_duration {
public:
// typestypedef time_res_traits rep_type;
typedef time_res_traits::day_type day_type;
typedef time_res_traits::hour_type hour_type;
typedef time_res_traits::min_type min_type;
typedef time_res_traits::sec_type sec_type;
typedef time_res_traits::fractional_seconds_type fractional_seconds_type;
typedef time_res_traits::tick_type tick_type;
typedef time_res_traits::impl_type impl_type;
// construct/copy/destruct
time_duration(hour_type, min_type, sec_type, fractional_seconds_type = 0);
time_duration();
time_duration(boost::date_time::special_values);
time_duration(impl_type);
// public member functions// private member functions
};Description<anchor id="id344570construct-copy-destruct"/><computeroutput>time_duration</computeroutput> construct/copy/destructtime_duration(hour_type hour, min_type min, sec_type sec,
fractional_seconds_type fs = 0);time_duration();time_duration(boost::date_time::special_values sv);Construct from special_values. time_duration(impl_type ticks);<anchor id="id318917-bb"/><computeroutput>time_duration</computeroutput> public member functions<anchor id="id394655-bb"/><computeroutput>time_duration</computeroutput> private member functionsStruct simple_time_rep3boost::posix_time::simple_time_repSimple implementation for the time rep. struct simple_time_rep {
// typestypedef gregorian::date date_type;
typedef time_duration time_duration_type;
// construct/copy/destruct
simple_time_rep(date_type, time_duration_type);
// public member functionsbool is_special() const;
bool is_pos_infinity() const;
bool is_neg_infinity() const;
bool is_not_a_date_time() const;
date_type day;
time_duration_type time_of_day;
};Description<anchor id="simple_time_repconstruct-copy-destruct"/><computeroutput>simple_time_rep</computeroutput> construct/copy/destructsimple_time_rep(date_type d, time_duration_type tod);<anchor id="id396812-bb"/><computeroutput>simple_time_rep</computeroutput> public member functionsboolis_special() const;boolis_pos_infinity() const;boolis_neg_infinity() const;boolis_not_a_date_time() const;Class posix_time_system_config3boost::posix_time::posix_time_system_configclass posix_time_system_config {
public:
// typestypedef simple_time_rep time_rep_type;
typedef gregorian::date date_type;
typedef gregorian::date_duration date_duration_type;
typedef time_duration time_duration_type;
typedef time_res_traits::tick_type int_type;
typedef time_res_traits resolution_traits;
// public member functions BOOST_STATIC_CONSTANT(boost::int64_t, tick_per_second = 1000000000) ;
};Description<anchor id="id322936-bb"/><computeroutput>posix_time_system_config</computeroutput> public member functionsBOOST_STATIC_CONSTANT(boost::int64_t , tick_per_second = 1000000000) ;Class millisec_posix_time_system_config3boost::posix_time::millisec_posix_time_system_configclass millisec_posix_time_system_config {
public:
// typestypedef boost::int64_t time_rep_type;
typedef gregorian::date date_type;
typedef gregorian::date_duration date_duration_type;
typedef time_duration time_duration_type;
typedef time_res_traits::tick_type int_type;
typedef time_res_traits::impl_type impl_type;
typedef time_res_traits resolution_traits;
// public member functions BOOST_STATIC_CONSTANT(boost::int64_t, tick_per_second = 1000000) ;
};Description<anchor id="id301094-bb"/><computeroutput>millisec_posix_time_system_config</computeroutput> public member functionsBOOST_STATIC_CONSTANT(boost::int64_t , tick_per_second = 1000000) ;Header <<ulink url="../../boost/date_time/posix_time/posix_time_duration.hpp">boost/date_time/posix_time/posix_time_duration.hpp</ulink>>namespace boost {
namespace posix_time {
class hours;
class minutes;
class seconds;
typedef date_time::subsecond_duration< time_duration, 1000 > millisec; // Allows expression of durations as milli seconds. typedef date_time::subsecond_duration< time_duration, 1000 > milliseconds;
typedef date_time::subsecond_duration< time_duration, 1000000 > microsec; // Allows expression of durations as micro seconds. typedef date_time::subsecond_duration< time_duration, 1000000 > microseconds;
typedef date_time::subsecond_duration< time_duration, 1000000000 > nanosec; // Allows expression of durations as nano seconds. typedef date_time::subsecond_duration< time_duration, 1000000000 > nanoseconds;
}
}Class hours3boost::posix_time::hoursAllows expression of durations as an hour count. class hours : public boost::posix_time::time_duration {
public:
// construct/copy/destruct
hours(long);
// public member functions
};Description<anchor id="hoursconstruct-copy-destruct"/><computeroutput>hours</computeroutput> construct/copy/destructhours(long h);<anchor id="id368002-bb"/><computeroutput>hours</computeroutput> public member functionsClass minutes3boost::posix_time::minutesAllows expression of durations as a minute count. class minutes : public boost::posix_time::time_duration {
public:
// construct/copy/destruct
minutes(long);
// public member functions
};Description<anchor id="minutesconstruct-copy-destruct"/><computeroutput>minutes</computeroutput> construct/copy/destructminutes(long m);<anchor id="id314036-bb"/><computeroutput>minutes</computeroutput> public member functionsClass seconds3boost::posix_time::secondsAllows expression of durations as a seconds count. class seconds : public boost::posix_time::time_duration {
public:
// construct/copy/destruct
seconds(long);
// public member functions
};Description<anchor id="secondsconstruct-copy-destruct"/><computeroutput>seconds</computeroutput> construct/copy/destructseconds(long s);<anchor id="id407627-bb"/><computeroutput>seconds</computeroutput> public member functionsHeader <<ulink url="../../boost/date_time/posix_time/posix_time_system.hpp">boost/date_time/posix_time/posix_time_system.hpp</ulink>>namespace boost {
namespace posix_time {
typedef date_time::split_timedate_system< posix_time_system_config, 1000000000 > posix_time_system;
typedef date_time::counted_time_rep< millisec_posix_time_system_config > int64_time_rep;
}
}Header <<ulink url="../../boost/date_time/posix_time/posix_time_types.hpp">boost/date_time/posix_time/posix_time_types.hpp</ulink>>namespace boost {
namespace posix_time {
typedef date_time::time_itr< ptime > time_iterator; // Iterator over a defined time duration. typedef date_time::second_clock< ptime::date_type, ptime > second_clock; // A time clock that has a resolution of one second. typedef date_time::microsec_clock< ptime > microsec_clock; // A time clock that has a resolution of one microsecond. typedef date_time::null_dst_rules< ptime::date_type, time_duration > no_dst; // Define a dst null dst rule for the posix_time system. typedef date_time::us_dst_rules< ptime::date_type, time_duration > us_dst; // Define US dst rule calculator for the posix_time system.
}
}Header <<ulink url="../../boost/date_time/posix_time/ptime.hpp">boost/date_time/posix_time/ptime.hpp</ulink>>namespace boost {
namespace posix_time {
class ptime;
}
}Class ptime3boost::posix_time::ptimeTime type with no timezone or other adjustments. class ptime {
public:
// typestypedef posix_time_system time_system_type;
typedef time_system_type::time_rep_type time_rep_type;
typedef time_system_type::time_duration_type time_duration_type;
typedef ptime time_type;
// construct/copy/destruct
ptime(gregorian::date, time_duration_type);
ptime(gregorian::date);
ptime(const time_rep_type &);
ptime(const special_values);
ptime();
// public member functions
};Description<anchor id="ptimeconstruct-copy-destruct"/><computeroutput>ptime</computeroutput> construct/copy/destructptime(gregorian::date d, time_duration_type td);Construct with date and offset in day. ptime(gregorian::date d);Construct a time at start of the given day (midnight). ptime(const time_rep_type & rhs);Copy from time_rep. ptime(const special_values sv);Construct from special value. ptime();<anchor id="id394759-bb"/><computeroutput>ptime</computeroutput> public member functionsHeader <<ulink url="../../boost/date_time/posix_time/time_formatters.hpp">boost/date_time/posix_time/time_formatters.hpp</ulink>>namespace boost {
namespace posix_time {
template<typename charT>
std::basic_string< charT >to_simple_string_type(time_duration td);
template<typename charT>
std::basic_string< charT >to_iso_string_type(time_duration td);
// Time to simple format CCYY-mmm-dd hh:mm:ss.fffffff. template<typename charT>
std::basic_string< charT >to_simple_string_type(ptime t);
template<typename charT>
std::basic_string< charT >to_simple_string_type(time_period tp);
template<typename charT>
std::basic_string< charT >to_iso_string_type(ptime t);
template<typename charT>
std::basic_string< charT >to_iso_extended_string_type(ptime t);
// Time duration to wstring -hh::mm::ss.fffffff. Example: 10:09:03.0123456. std::wstringto_simple_wstring(time_duration td);
// Time duration in iso format -hhmmss,fffffff Example: 10:09:03,0123456. std::wstringto_iso_wstring(time_duration td);
std::wstringto_simple_wstring(ptime t);
// Convert to wstring of form [YYYY-mmm-DD HH:MM::SS.ffffff/YYYY-mmm-DD HH:MM::SS.fffffff]. std::wstringto_simple_wstring(time_period tp);
// Convert iso short form YYYYMMDDTHHMMSS where T is the date-time separator. std::wstringto_iso_wstring(ptime t);
// Convert to form YYYY-MM-DDTHH:MM:SS where T is the date-time separator. std::wstringto_iso_extended_wstring(ptime t);
template<typename charT>
std::basic_istream< charT > &operator>>(std::basic_istream< charT > & is, time_duration & td);
template<typename charT>
std::basic_istream< charT > &operator>>(std::basic_istream< charT > & is, ptime & pt);
template<typename charT>
std::basic_istream< charT > &operator>>(std::basic_istream< charT > &, time_period &);
}
}Function template operator>>3boost::posix_time::operator>>template<typename charT>
std::basic_istream< charT > &operator>>(std::basic_istream< charT > & is, time_period & tp);Descriptionoperator>> for time_period. time_period must be in "[date time_duration/date time_duration]" format. Header <<ulink url="../../boost/date_time/posix_time/time_formatters_limited.hpp">boost/date_time/posix_time/time_formatters_limited.hpp</ulink>>namespace boost {
namespace posix_time {
// Time duration to string -hh::mm::ss.fffffff. Example: 10:09:03.0123456. std::stringto_simple_string(time_duration td);
// Time duration in iso format -hhmmss,fffffff Example: 10:09:03,0123456. std::stringto_iso_string(time_duration td);
// Time to simple format CCYY-mmm-dd hh:mm:ss.fffffff. std::stringto_simple_string(ptime t);
// Convert to string of form [YYYY-mmm-DD HH:MM::SS.ffffff/YYYY-mmm-DD HH:MM::SS.fffffff]. std::stringto_simple_string(time_period tp);
// Convert iso short form YYYYMMDDTHHMMSS where T is the date-time separator. std::stringto_iso_string(ptime t);
// Convert to form YYYY-MM-DDTHH:MM:SS where T is the date-time separator. std::stringto_iso_extended_string(ptime t);
// ostream operator for posix_time::time_duration template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os,
const time_duration & td);
// ostream operator for posix_time::ptime template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os, const ptime & t);
// ostream operator for posix_time::time_period template<typename charT, typename traits>
std::basic_ostream< charT, traits > &operator<<(std::basic_ostream< charT, traits > & os,
const time_period & tp);
}
}Header <<ulink url="../../boost/date_time/posix_time/time_parsers.hpp">boost/date_time/posix_time/time_parsers.hpp</ulink>>namespace boost {
namespace posix_time {
time_duration duration_from_string(const std::string &);
ptimetime_from_string(const std::string & s);
ptimefrom_iso_string(const std::string & s);
}
}Function duration_from_string3boost::posix_time::duration_from_stringCreates a time_duration object from a delimited string. time_duration duration_from_string(const std::string & s);DescriptionExpected format for string is "[-]h[h][:mm][:ss][.fff]". A negative duration will be created if the first character in string is a '-', all other '-' will be treated as delimiters. Accepted delimiters are "-:,.". Header <<ulink url="../../boost/date_time/posix_time/time_period.hpp">boost/date_time/posix_time/time_period.hpp</ulink>>namespace boost {
namespace posix_time {
typedef date_time::period< ptime, time_duration > time_period; // Time period type.
}
}DouglasGregordgregor -at- cs.indiana.edu2001200220032004Douglas GregorUse, modification and distribution is 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)Boost.FunctionIntroductionThe Boost.Function library contains a family of class templates
that are function object wrappers. The notion is similar to a
generalized callback. It shares features with function pointers in
that both define a call interface (e.g., a function taking two integer
arguments and returning a floating-point value) through which some
implementation can be called, and the implementation that is invoked
may change throughout the course of the program. Generally, any place in which a function pointer would be used
to defer a call or make a callback, Boost.Function can be used instead
to allow the user greater flexibility in the implementation of the
target. Targets can be any 'compatible' function object (or function
pointer), meaning that the arguments to the interface designated by
Boost.Function can be converted to the arguments of the target
function object.History & Compatibility NotesVersion 1.30.0: All features deprecated in version 1.29.0 have
been removed from Boost.Function.boost::function
and boost::functionN objects
can be assigned to 0 (semantically equivalent to calling
clear()) and
compared against 0 (semantically equivalent to calling
empty()).The Boost.Function code is now generated
entirely by the Preprocessor library,
so it is now possible to generate
boost::function and
boost::functionN class
templates for any number of arguments.The
boost::bad_function_call exception class
was introduced.Version 1.29.0:
Boost.Function has been partially redesigned to minimize the
interface and make it cleaner. Several seldom- or never-used
features of the older Boost.Function have been deprecated and will
be removed in the near future. Here is a list of features that have
been deprecated, the likely impact of the deprecations, and how to
adjust your code:
The boost::function class template syntax has
changed. The old syntax, e.g., boost::function<int, float,
double, std::string>, has been changed to a more natural
syntax boost::function<int (float, double,
std::string)>, where all return and argument types are
encoded in a single function type parameter. Any other template
parameters (e.g., the Allocator) follow this single
parameter. The resolution to this change depends on the
abilities of your compiler: if your compiler supports template
partial specialization and can parse function types (most do), modify
your code to use the newer
syntax (preferable) or directly use one of the
functionN classes whose syntax has not
changed. If your compiler does not support template partial
specialization or function types, you must take the latter option and
use the numbered Boost.Function classes. This option merely requires
changing types such as boost::function<void, int, int>
to boost::function2<void, int, int> (adding the number of
function arguments to the end of the class name). Support for the old syntax with the
boost::function class template will persist for a short
while, but will eventually be removed so that we can provide better
error messages and link compatibility. The invocation
policy template parameter (Policy) has been deprecated
and will be removed. There is no direct equivalent to this rarely
used feature.The mixin template parameter
(Mixin) has been deprecated and will be removed. There
is not direct equivalent to this rarely used feature.The
set methods have been deprecated and will be
removed. Use the assignment operator instead.Tutorial Boost.Function has two syntactical forms: the preferred form
and the portable form. The preferred form fits more closely with the
C++ language and reduces the number of separate template parameters
that need to be considered, often improving readability; however, the
preferred form is not supported on all platforms due to compiler
bugs. The compatible form will work on all compilers supported by
Boost.Function. Consult the table below to determine which syntactic
form to use for your compiler.
Preferred syntaxPortable syntaxGNU C++ 2.95.x, 3.0.x, 3.1.xComeau C++ 4.2.45.2SGI MIPSpro 7.3.0Intel C++ 5.0, 6.0Compaq's cxx 6.2Microsoft Visual C++ 7.1Any compiler supporting the preferred syntaxMicrosoft Visual C++ 6.0, 7.0Borland C++ 5.5.1Sun WorkShop 6 update 2 C++ 5.3Metrowerks CodeWarrior 8.1 If your compiler does not appear in this list, please try the preferred syntax and report your results to the Boost list so that we can keep this table up-to-date.Basic Usage A function wrapper is defined simply
by instantiating the function class
template with the desired return type and argument types, formulated
as a C++ function type. Any number of arguments may be supplied, up to
some implementation-defined limit (10 is the default maximum). The
following declares a function object wrapper
f that takes two
int parameters and returns a
float:
Preferred syntaxPortable syntaxboost::function<float (int x, int y)> f;boost::function2<float, int, int> f; By default, function object wrappers are empty, so we can create a
function object to assign to f:
struct int_div {
float operator()(int x, int y) const { return ((float)x)/y; };
};f = int_div(); Now we can use f to execute
the underlying function object
int_div:
std::cout << f(5, 3) << std::endl; We are free to assign any compatible function object to
f. If
int_div had been declared to take two
long operands, the implicit
conversions would have been applied to the arguments without any user
interference. The only limit on the types of arguments is that they be
CopyConstructible, so we can even use references and arrays:
Preferred syntaxboost::function<void (int values[], int n, int& sum, float& avg)> sum_avg;Portable syntaxboost::function4<void, int*, int, int&, float&> sum_avg;void do_sum_avg(int values[], int n, int& sum, float& avg)
{
sum = 0;
for (int i = 0; i < n; i++)
sum += values[i];
avg = (float)sum / n;
}sum_avg = &do_sum_avg; Invoking a function object wrapper that does not actually
contain a function object is a precondition violation, much like
trying to call through a null function pointer, and will throw a bad_function_call exception). We can check for an
empty function object wrapper by using it in a boolean context (it evaluates true if the wrapper is not empty) or compare it against 0. For instance:
if (f)
std::cout << f(5, 3) << std::endl;
else
std::cout << "f has no target, so it is unsafe to call" << std::endl; Alternatively,
empty()
method will return whether or not the wrapper is empty. Finally, we can clear out a function target by assigning it to 0 or by calling the clear() member function, e.g.,
f = 0;Free functions Free function pointers can be considered singleton function objects with const function call operators, and can therefore be directly used with the function object wrappers:
float mul_ints(int x, int y) { return ((float)x) * y; }f = &mul_ints; Note that the & isn't really necessary unless you happen to be using Microsoft Visual C++ version 6. Member functions In many systems, callbacks often call to member functions of a
particular object. This is often referred to as "argument binding",
and is beyond the scope of Boost.Function. The use of member functions
directly, however, is supported, so the following code is valid:
struct X {
int foo(int);
};Preferred syntaxPortable syntaxboost::function<int (X*, int)> f;
f = &X::foo;
X x;
f(&x, 5);boost::function2<int, X*, int> f;
f = &X::foo;
X x;
f(&x, 5); Several libraries exist that support argument binding. Three such libraries are summarized below:
Bind. This library allows binding of
arguments for any function object. It is lightweight and very
portable.The C++ Standard library. Using
std::bind1st and
std::mem_fun together one can bind
the object of a pointer-to-member function for use with
Boost.Function:
Preferred syntaxPortable syntaxboost::function<int (int)> f;
X x;
f = std::bind1st(
std::mem_fun(&X::foo), &x);
f(5); // Call x.foo(5)boost::function1<int, int> f;
X x;
f = std::bind1st(
std::mem_fun(&X::foo), &x);
f(5); // Call x.foo(5)The Lambda library. This library provides a powerful composition mechanism to construct function objects that uses very natural C++ syntax. Lambda requires a compiler that is reasonably conformant to the C++ standard. References to Function Objects In some cases it is
expensive (or semantically incorrect) to have Boost.Function clone a
function object. In such cases, it is possible to request that
Boost.Function keep only a reference to the actual function
object. This is done using the ref
and cref functions to wrap a
reference to a function object:
Preferred syntaxPortable syntaxstateful_type a_function_object;
boost::function<int (int)> f;
f = boost::ref(a_function_object);
boost::function<int (int)> f2(f);stateful_type a_function_object;
boost::function1<int, int> f;
f = boost::ref(a_function_object);
boost::function1<int, int> f2(f); Here, f will not make a copy
of a_function_object, nor will
f2 when it is targeted to
f's reference to
a_function_object. Additionally, when
using references to function objects, Boost.Function will not throw
exceptions during assignment or construction.
Comparing Boost.Function function objectsFunction object wrappers can be compared via ==
or != against any function object that can be stored
within the wrapper. If the function object wrapper contains a
function object of that type, it will be compared against the given
function object (which must be
EqualityComparable). For instance:int compute_with_X(X*, int);
f = &X::foo;
assert(f == &X::foo);
assert(&compute_with_X != f);When comparing against an instance of
reference_wrapper, the address
of the object in the
reference_wrapper is compared
against the address of the object stored by the function object
wrapper:a_stateful_object so1, so2;
f = boost::ref(so1);
assert(f == boost::ref(so1));
assert(f == so1); // Only if a_stateful_object is EqualityComparable
assert(f != boost::ref(so2));ReferenceDefinitionsA function object f is
compatible if for the given set of argument
types Arg1,
Arg2, ...,
ArgN and a
return type ResultType, the
appropriate following function is well-formed:
// if ResultType is not void
ResultType foo(Arg1 arg1, Arg2 arg2, ..., ArgN argN)
{
return f(arg1, arg2, ..., argN);
}
// if ResultType is void
ResultType foo(Arg1 arg1, Arg2 arg2, ..., ArgN argN)
{
f(arg1, arg2, ..., argN);
}
A special provision is made for pointers to member
functions. Though they are not function objects, Boost.Function
will adapt them internally to function objects. This requires
that a pointer to member function of the form R
(X::*mf)(Arg1, Arg2, ..., ArgN)
cv-quals be adapted to a
function object with the following function call operator
overloads:
template<typename P>
R operator()(cv-quals P& x, Arg1 arg1, Arg2 arg2, ..., ArgN argN) const
{
return (*x).*mf(arg1, arg2, ..., argN);
}
A function object f of
type F is
stateless if it is a function pointer or if
boost::is_stateless<T>
is true. The construction of or copy to a Boost.Function object
from a stateless function object will not cause exceptions to be
thrown and will not allocate any storage.
Header <<ulink url="../../boost/function.hpp">boost/function.hpp</ulink>>namespace boost {
class bad_function_call;
class function_base;
template<typename R, typename T1, typename T2, ..., typename TN,
typename Allocator = std::allocator<void> >
class functionN;
template<typename T1, typename T2, ..., typename TN, typename Allocator>
void swap(functionN<T1, T2, ..., TN, Allocator>&,
functionN<T1, T2, ..., TN, Allocator>&);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator==(const functionN<T1, T2, ..., TN, Allocator>&, Functor);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator==(Functor, const functionN<T1, T2, ..., TN, Allocator>&);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator==(const functionN<T1, T2, ..., TN, Allocator>&,
reference_wrapper<Functor>);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator==(reference_wrapper<Functor>,
const functionN<T1, T2, ..., TN, Allocator>&);
template<typename T1, typename T2, ..., typename TN, typename Allocator1,
typename U1, typename U2, ..., typename UN, typename Allocator2>
voidoperator==(const functionN<T1, T2, ..., TN, Allocator1>&,
const functionN<U1, U2, ..., UN, Allocator2>&);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator!=(const functionN<T1, T2, ..., TN, Allocator>&, Functor);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator!=(Functor, const functionN<T1, T2, ..., TN, Allocator>&);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator!=(const functionN<T1, T2, ..., TN, Allocator>&,
reference_wrapper<Functor>);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator!=(reference_wrapper<Functor>,
const functionN<T1, T2, ..., TN, Allocator>&);
template<typename T1, typename T2, ..., typename TN, typename Allocator1,
typename U1, typename U2, ..., typename UN, typename Allocator2>
voidoperator!=(const functionN<T1, T2, ..., TN, Allocator1>&,
const functionN<U1, U2, ..., UN, Allocator2>&);
template<typename Signature, typename Allocator = std::allocator<void> >
class function;
template<typename Signature, typename Allocator>
void swap(function<Signature, Allocator>&,
function<Signature, Allocator>&);
template<typename Signature, typename Allocator, typename Functor>
booloperator==(const function<Signature, Allocator>&, Functor);
template<typename Signature, typename Allocator, typename Functor>
booloperator==(Functor, const function<Signature, Allocator>&);
template<typename Signature, typename Allocator, typename Functor>
booloperator==(const function<Signature, Allocator>&,
reference_wrapper<Functor>);
template<typename Signature, typename Allocator, typename Functor>
booloperator==(reference_wrapper<Functor>,
const function<Signature, Allocator>&);
template<typename Signature1, typename Allocator1, typename Signature2,
typename Allocator2>
voidoperator==(const function<Signature1, Allocator1>&,
const function<Signature2, Allocator2>&);
template<typename Signature, typename Allocator, typename Functor>
booloperator!=(const function<Signature, Allocator>&, Functor);
template<typename Signature, typename Allocator, typename Functor>
booloperator!=(Functor, const function<Signature, Allocator>&);
template<typename Signature, typename Allocator, typename Functor>
booloperator!=(const function<Signature, Allocator>&,
reference_wrapper<Functor>);
template<typename Signature, typename Allocator, typename Functor>
booloperator!=(reference_wrapper<Functor>,
const function<Signature, Allocator>&);
template<typename Signature1, typename Allocator1, typename Signature2,
typename Allocator2>
voidoperator!=(const function<Signature1, Allocator1>&,
const function<Signature2, Allocator2>&);
}Class bad_function_call3boost::bad_function_callAn exception type thrown when an instance of a function object is empty when invoked.class bad_function_call : public std::runtime_error {
public:
// construct/copy/destruct
bad_function_call();
};Description<anchor id="bad_function_callconstruct-copy-destruct"/><computeroutput>bad_function_call</computeroutput> construct/copy/destructbad_function_call();EffectsConstructs a bad_function_call exception object.Class function_base3boost::function_baseThe common base class for all Boost.Function
objects. Objects of type function_base may not be created
directly.class function_base {
public:
// capacitybool empty() const;
// target accesstemplate<typename Functor> Functor* target();
template<typename Functor> const Functor* target() const;
template<typename Functor> bool contains(const Functor&) const;
};Description<anchor id="id429695-bb"/><computeroutput>function_base</computeroutput> capacityboolempty() const;Returnsfalse if this has a target, and true otherwise.ThrowsWill not throw.<anchor id="id363180-bb"/><computeroutput>function_base</computeroutput> target accesstemplate<typename Functor> Functor*target();
template<typename Functor> const Functor*target() const;ReturnsIf this stores a target of type
Functor, returns the address of the
target. Otherwise, returns the NULL
pointer.ThrowsWill not throw.template<typename Functor> boolcontains(const Functor& f) const;Returnstrue if this->target<Functor>() is non-NULL and function_equal(*(this->target<Functor>()), f)Class template functionN3boost::functionNA set of generalized function pointers that can be used for callbacks or wrapping function objects.template<typename R, typename T1, typename T2, ..., typename TN,
typename Allocator = std::allocator<void> >
class functionN : public function_base {
public:
// typestypedef R result_type;
typedef Allocator allocator_type;
typedef T1 argument_type; // If N == 1typedef T1 first_argument_type; // If N == 2typedef T2 second_argument_type; // If N == 2typedef T1 arg1_type;
typedef T2 arg2_type;
.
.
.
typedef TN argN_type;
// static constantsstaticconstint arity = N;
// Lambda library supporttemplate<typename Args>
struct sig {
// typestypedef result_type type;
};
// construct/copy/destruct
functionN();
functionN(const functionN&);
template<typename F> functionN(F);
functionN& operator=(const functionN&);
~functionN();
// modifiersvoid swap(const functionN&);
void clear();
// capacitybool empty() const;
operator safe_bool() const;
booloperator!() const;
// target accesstemplate<typename Functor> Functor* target();
template<typename Functor> const Functor* target() const;
template<typename Functor> bool contains(const Functor&) const;
// invocationresult_typeoperator()(arg1_type, arg2_type, ..., argN_type) const;
};
// specialized algorithmstemplate<typename T1, typename T2, ..., typename TN, typename Allocator>
void swap(functionN<T1, T2, ..., TN, Allocator>&,
functionN<T1, T2, ..., TN, Allocator>&);
// comparison operatorstemplate<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator==(const functionN<T1, T2, ..., TN, Allocator>&, Functor);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator==(Functor, const functionN<T1, T2, ..., TN, Allocator>&);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator==(const functionN<T1, T2, ..., TN, Allocator>&,
reference_wrapper<Functor>);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator==(reference_wrapper<Functor>,
const functionN<T1, T2, ..., TN, Allocator>&);
template<typename T1, typename T2, ..., typename TN, typename Allocator1,
typename U1, typename U2, ..., typename UN, typename Allocator2>
voidoperator==(const functionN<T1, T2, ..., TN, Allocator1>&,
const functionN<U1, U2, ..., UN, Allocator2>&);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator!=(const functionN<T1, T2, ..., TN, Allocator>&, Functor);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator!=(Functor, const functionN<T1, T2, ..., TN, Allocator>&);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator!=(const functionN<T1, T2, ..., TN, Allocator>&,
reference_wrapper<Functor>);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator!=(reference_wrapper<Functor>,
const functionN<T1, T2, ..., TN, Allocator>&);
template<typename T1, typename T2, ..., typename TN, typename Allocator1,
typename U1, typename U2, ..., typename UN, typename Allocator2>
voidoperator!=(const functionN<T1, T2, ..., TN, Allocator1>&,
const functionN<U1, U2, ..., UN, Allocator2>&);DescriptionClass template functionN is
actually a family of related classes function0, function1, etc., up to some
implementation-defined maximum. In this context, N
refers to the number of parameters.<anchor id="functionNconstruct-copy-destruct"/><computeroutput>functionN</computeroutput> construct/copy/destructfunctionN();Postconditionsthis->empty()ThrowsWill not throw.functionN(const functionN& f);PostconditionsContains a copy of the f's target, if it has one, or is empty if f.empty().ThrowsWill not throw unless copying the target of f throws.template<typename F> functionN(F f);RequiresF is a function object Callable from this.Postconditions*this targets a copy of f if f is nonempty, or this->empty() if f is empty.ThrowsWill not throw when f is a stateless function object.functionN& operator=(const functionN& f);Postconditions*this targets a copy of f's target, if it has one, or is empty if f.empty().ThrowsWill not throw when the target of f is a stateless function object or a reference to the function object.~functionN();EffectsIf !this->empty(), destroys the target of this.<anchor id="id363207-bb"/><computeroutput>functionN</computeroutput> modifiersvoidswap(const functionN& f);EffectsInterchanges the targets of *this and f.ThrowsWill not throw.voidclear();Postconditionsthis->empty()ThrowsWill not throw.<anchor id="id218197-bb"/><computeroutput>functionN</computeroutput> capacityboolempty() const;Returnsfalse if this has a target, and true otherwise.ThrowsWill not throw.operator safe_bool() const;ReturnsA safe_bool that evaluates false in a boolean context when this->empty(), and true otherwise.ThrowsWill not throw.booloperator!() const;Returnsthis->empty()ThrowsWill not throw.<anchor id="id311150-bb"/><computeroutput>functionN</computeroutput> target accesstemplate<typename Functor> Functor*target();
template<typename Functor> const Functor*target() const;ReturnsIf this stores a target of type
Functor, returns the address of the
target. Otherwise, returns the NULL
pointer.ThrowsWill not throw.template<typename Functor> boolcontains(const Functor& f) const;Returnstrue if this->target<Functor>() is non-NULL and function_equal(*(this->target<Functor>()), f)<anchor id="id399301-bb"/><computeroutput>functionN</computeroutput> invocationresult_typeoperator()(arg1_type a1, arg2_type a2, ... , argN_type aN) const;Effectsf(a1, a2, ..., aN), where f is the target of *this.Returnsif R is void, nothing is returned; otherwise, the return value of the call to f is returned.Throwsbad_function_call if !this->empty(). Otherwise, may through any exception thrown by the target function f.<anchor id="id253632-bb"/><computeroutput>functionN</computeroutput> specialized algorithmstemplate<typename T1, typename T2, ..., typename TN, typename Allocator>
voidswap(functionN<T1, T2, ..., TN, Allocator>& f1,
functionN<T1, T2, ..., TN, Allocator>& f2);Effectsf1.swap(f2)ThrowsWill not throw.<anchor id="id443814-bb"/><computeroutput>functionN</computeroutput> comparison operatorstemplate<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator==(const functionN<T1, T2, ..., TN, Allocator>& f, Functor g);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator==(Functor g, const functionN<T1, T2, ..., TN, Allocator>& f);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator==(const functionN<T1, T2, ..., TN, Allocator>& f,
reference_wrapper<Functor> g);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator==(reference_wrapper<Functor> g,
const functionN<T1, T2, ..., TN, Allocator>& f);
template<typename T1, typename T2, ..., typename TN, typename Allocator1,
typename U1, typename U2, ..., typename UN, typename Allocator2>
voidoperator==(const functionN<T1, T2, ..., TN, Allocator1>& f1,
const functionN<U1, U2, ..., UN, Allocator2>& f2);ReturnsTrue when f stores an object of
type Functor and one of the following conditions applies:
g is of type
reference_wrapper<Functor>
and f.target<Functor>() == g.get_pointer().g is not of type
reference_wrapper<Functor>
and
function_equal(*(f.target<Functor>()),
g).NotesfunctionN
objects are not
EqualityComparable.RationaleThe safe_bool conversion
opens a loophole whereby two functionN
instances can be compared via ==, although this
is not feasible to implement. The undefined void
operator== closes the loophole and ensures a
compile-time or link-time error.template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator!=(const functionN<T1, T2, ..., TN, Allocator>& f, Functor g);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator!=(Functor g, const functionN<T1, T2, ..., TN, Allocator>& f);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator!=(const functionN<T1, T2, ..., TN, Allocator>& f,
reference_wrapper<Functor> g);
template<typename T1, typename T2, ..., typename TN, typename Allocator,
typename Functor>
booloperator!=(reference_wrapper<Functor> g,
const functionN<T1, T2, ..., TN, Allocator>& f);
template<typename T1, typename T2, ..., typename TN, typename Allocator1,
typename U1, typename U2, ..., typename UN, typename Allocator2>
voidoperator!=(const functionN<T1, T2, ..., TN, Allocator1>& f1,
const functionN<U1, U2, ..., UN, Allocator2>& f2);ReturnsTrue when f does not store an
object of type Functor or it stores an object of
type Functor and one of the following conditions
applies:
g is of type
reference_wrapper<Functor>
and f.target<Functor>() != g.get_pointer().g is not of type
reference_wrapper<Functor>
and !function_equal(*(f.target<Functor>()), g).NotesfunctionN
objects are not
EqualityComparable.RationaleThe safe_bool conversion
opens a loophole whereby two functionN
instances can be compared via !=, although this
is not feasible to implement. The undefined void
operator!= closes the loophole and ensures a
compile-time or link-time error.Class template function3boost::functionA generalized function pointer that can be used for
callbacks or wrapping function objects.template<typename Signature, // Function type R (T1, T2, ..., TN)typename Allocator = std::allocator<void> >
class function : public functionN<R, T1, T2, ..., TN, Allocator> {
public:
// typestypedef R result_type;
typedef Allocator allocator_type;
typedef T1 argument_type; // If N == 1typedef T1 first_argument_type; // If N == 2typedef T2 second_argument_type; // If N == 2typedef T1 arg1_type;
typedef T2 arg2_type;
.
.
.
typedef TN argN_type;
// static constantsstaticconstint arity = N;
// Lambda library supporttemplate<typename Args>
struct sig {
// typestypedef result_type type;
};
// construct/copy/destruct
function();
function(const functionN&);
function(const function&);
template<typename F> function(F);
function& operator=(const functionN&);
function& operator=(const function&);
~function();
// modifiersvoid swap(const function&);
void clear();
// capacitybool empty() const;
operator safe_bool() const;
booloperator!() const;
// target accesstemplate<typename Functor> Functor* target();
template<typename Functor> const Functor* target() const;
template<typename Functor> bool contains(const Functor&) const;
// invocationresult_typeoperator()(arg1_type, arg2_type, ..., argN_type) const;
};
// specialized algorithmstemplate<typename Signature, typename Allocator>
void swap(function<Signature, Allocator>&, function<Signature, Allocator>&);
// comparison operatorstemplate<typename Signature, typename Allocator, typename Functor>
booloperator==(const function<Signature, Allocator>&, Functor);
template<typename Signature, typename Allocator, typename Functor>
booloperator==(Functor, const function<Signature, Allocator>&);
template<typename Signature, typename Allocator, typename Functor>
booloperator==(const function<Signature, Allocator>&,
reference_wrapper<Functor>);
template<typename Signature, typename Allocator, typename Functor>
booloperator==(reference_wrapper<Functor>,
const function<Signature, Allocator>&);
template<typename Signature1, typename Allocator1, typename Signature2,
typename Allocator2>
voidoperator==(const function<Signature1, Allocator1>&,
const function<Signature2, Allocator2>&);
template<typename Signature, typename Allocator, typename Functor>
booloperator!=(const function<Signature, Allocator>&, Functor);
template<typename Signature, typename Allocator, typename Functor>
booloperator!=(Functor, const function<Signature, Allocator>&);
template<typename Signature, typename Allocator, typename Functor>
booloperator!=(const function<Signature, Allocator>&,
reference_wrapper<Functor>);
template<typename Signature, typename Allocator, typename Functor>
booloperator!=(reference_wrapper<Functor>,
const function<Signature, Allocator>&);
template<typename Signature1, typename Allocator1, typename Signature2,
typename Allocator2>
voidoperator!=(const function<Signature1, Allocator1>&,
const function<Signature2, Allocator2>&);DescriptionClass template function is a thin
wrapper around the numbered class templates function0, function1, etc. It accepts a
function type with N arguments and will will derive from
functionN instantiated with the arguments
it receives.The semantics of all operations in class template
function are equivalent to that of the
underlying functionN object, although
additional member functions are required to allow proper copy
construction and copy assignment of function objects.<anchor id="boost.functionconstruct-copy-destruct"/><computeroutput>function</computeroutput> construct/copy/destructfunction();Postconditionsthis->empty()ThrowsWill not throw.function(const functionN& f);PostconditionsContains a copy of the f's target, if it has one, or is empty if f.empty().ThrowsWill not throw unless copying the target of f throws.function(const function& f);PostconditionsContains a copy of the f's target, if it has one, or is empty if f.empty().ThrowsWill not throw unless copying the target of f throws.template<typename F> function(F f);RequiresF is a function object Callable from this.Postconditions*this targets a copy of f if f is nonempty, or this->empty() if f is empty.ThrowsWill not throw when f is a stateless function object.function& operator=(const functionN& f);Postconditions*this targets a copy of f's target, if it has one, or is empty if f.empty()ThrowsWill not throw when the target of f is a stateless function object or a reference to the function object.function& operator=(const function& f);Postconditions*this targets a copy of f's target, if it has one, or is empty if f.empty()ThrowsWill not throw when the target of f is a stateless function object or a reference to the function object.~function();EffectsIf !this->empty(), destroys the target of this.<anchor id="id273706-bb"/><computeroutput>function</computeroutput> modifiersvoidswap(const function& f);EffectsInterchanges the targets of *this and f.ThrowsWill not throw.voidclear();Postconditionsthis->empty()ThrowsWill not throw.<anchor id="id401776-bb"/><computeroutput>function</computeroutput> capacityboolempty() const;Returnsfalse if this has a target, and true otherwise.ThrowsWill not throw.operator safe_bool() const;ReturnsA safe_bool that evaluates false in a boolean context when this->empty(), and true otherwise.ThrowsWill not throw.booloperator!() const;Returnsthis->empty()ThrowsWill not throw.<anchor id="id407989-bb"/><computeroutput>function</computeroutput> target accesstemplate<typename Functor> Functor*target();
template<typename Functor> const Functor*target() const;ReturnsIf this stores a target of type
Functor, returns the address of the
target. Otherwise, returns the NULL
pointer.ThrowsWill not throw.template<typename Functor> boolcontains(const Functor& f) const;Returnstrue if this->target<Functor>() is non-NULL and function_equal(*(this->target<Functor>()), f)<anchor id="id355827-bb"/><computeroutput>function</computeroutput> invocationresult_typeoperator()(arg1_type a1, arg2_type a2, ... , argN_type aN) const;Effectsf(a1, a2, ..., aN), where f is the target of *this.Returnsif R is void, nothing is returned; otherwise, the return value of the call to f is returned.Throwsbad_function_call if !this->empty(). Otherwise, may through any exception thrown by the target function f.<anchor id="id372143-bb"/><computeroutput>function</computeroutput> specialized algorithmstemplate<typename Signature, typename Allocator>
voidswap(function<Signature, Allocator>& f1,
function<Signature, Allocator>& f2);Effectsf1.swap(f2)ThrowsWill not throw.<anchor id="id284910-bb"/><computeroutput>function</computeroutput> comparison operatorstemplate<typename Signature, typename Allocator, typename Functor>
booloperator==(const function<Signature, Allocator>& f, Functor g);
template<typename Signature, typename Allocator, typename Functor>
booloperator==(Functor g, const function<Signature, Allocator>& f);
template<typename Signature, typename Allocator, typename Functor>
booloperator==(const function<Signature, Allocator>& f,
reference_wrapper<Functor> g);
template<typename Signature, typename Allocator, typename Functor>
booloperator==(reference_wrapper<Functor> g,
const function<Signature, Allocator>& f);
template<typename Signature1, typename Allocator1, typename Signature2,
typename Allocator2>
voidoperator==(const function<Signature1, Allocator1>& f1,
const function<Signature2, Allocator2>& f2);ReturnsTrue when f stores an object of
type Functor and one of the following conditions applies:
g is of type
reference_wrapper<Functor>
and f.target<Functor>() == g.get_pointer().g is not of type
reference_wrapper<Functor>
and function_equals(*(f.target<Functor>()), g).Notesfunction
objects are not
EqualityComparable.RationaleThe safe_bool conversion
opens a loophole whereby two function
instances can be compared via ==, although this
is not feasible to implement. The undefined void
operator== closes the loophole and ensures a
compile-time or link-time error.template<typename Signature, typename Allocator, typename Functor>
booloperator!=(const function<Signature, Allocator>& f, Functor g);
template<typename Signature, typename Allocator, typename Functor>
booloperator!=(Functor g, const function<Signature, Allocator>& f);
template<typename Signature, typename Allocator, typename Functor>
booloperator!=(const function<Signature, Allocator>& f,
reference_wrapper<Functor> g);
template<typename Signature, typename Allocator, typename Functor>
booloperator!=(reference_wrapper<Functor> g,
const function<Signature, Allocator>& f);
template<typename Signature1, typename Allocator1, typename Signature2,
typename Allocator2>
voidoperator!=(const function<Signature1, Allocator1>& f1,
const function<Signature2, Allocator2>& f2);ReturnsTrue when f does not store an
object of type Functor or it stores an object of
type Functor and one of the following conditions
applies:
g is of type
reference_wrapper<Functor>
and f.target<Functor>() != g.get_pointer().g is not of type
reference_wrapper<Functor>
and !function_equals(*(f.target<Functor>()), g).Notesfunction
objects are not
EqualityComparable.RationaleThe safe_bool conversion
opens a loophole whereby two function
instances can be compared via !=, although this
is not feasible to implement. The undefined void
operator!= closes the loophole and ensures a
compile-time or link-time error.Header <<ulink url="../../boost/function_equal.hpp">boost/function_equal.hpp</ulink>>namespace boost {
template<typename F, typename G> bool function_equal(const F&, const G&);
}Function template function_equal3boost::function_equalCompare two function objects for equality.template<typename F, typename G> bool function_equal(const F& f, const G& g);DescriptionReturnsf == g.ThrowsOnly if f == g throws.Frequently Asked QuestionsWhy can't I compare
boost::function objects with
operator== or
operator!=?Comparison between boost::function
objects cannot be implemented "well", and therefore will not be
implemented. The typical semantics requested for f ==
g given boost::function objects
f and g are:If f and g
store function objects of the same type, use that type's
operator== to compare
them.If f and g
store function objects of different types, return
false.The problem occurs when the type of the function objects
stored by both f and g doesn't have an
operator==: we would like the expression f ==
g to fail to compile, as occurs with, e.g., the standard
containers. However, this is not implementable for
boost::function because it necessarily
"erases" some type information after it has been assigned a
function object, so it cannot try to call
operator== later: it must either find a way to call
operator== now, or it will never be able to call it
later. Note, for instance, what happens if you try to put a
float value into a
boost::function object: you will get an
error at the assignment operator or constructor, not in
operator(), because the function-call expression
must be bound in the constructor or assignment operator.The most promising approach is to find a method of
determining if operator== can be called for a
particular type, and then supporting it only when it is
available; in other situations, an exception would be
thrown. However, to date there is no known way to detect if an
arbitrary operator expression f == g is suitably
defined. The best solution known has the following undesirable
qualities:Fails at compile-time for objects where
operator== is not accessible (e.g., because it is
private).Fails at compile-time if calling
operator== is ambiguous.Appears to be correct if the
operator== declaration is correct, even though
operator== may not compile.All of these problems translate into failures in the
boost::function constructors or
assignment operator, even if the user never invokes
operator==. We can't do that to users.The other option is to place the burden on users that want
to use operator==, e.g., by providing an
is_equality_comparable trait they may
specialize. This is a workable solution, but is dangerous in
practice, because forgetting to specialize the trait will result
in unexpected exceptions being thrown from
boost::function's
operator==. This essentially negates the usefulness
of operator== in the context in which it is most
desired: multitarget callbacks. The
Signals library has a way around
this.I see void pointers; is this [mess] type safe?Yes, boost::function is type
safe even though it uses void pointers and pointers to functions
returning void and taking no arguments. Essentially, all type
information is encoded in the functions that manage and invoke
function pointers and function objects. Only these functions are
instantiated with the exact type that is pointed to by the void
pointer or pointer to void function. The reason that both are required
is that one may cast between void pointers and object pointers safely
or between different types of function pointers (provided you don't
invoke a function pointer with the wrong type). Why are there workarounds for void returns? C++ allows them!Void returns are permitted by the C++ standard, as in this code snippet:
void f();
void g() { return f(); } This is a valid usage of boost::function because void returns are not used. With void returns, we would attempting to compile ill-formed code similar to:
int f();
void g() { return f(); } In essence, not using void returns allows
boost::function to swallow a return value. This is
consistent with allowing the user to assign and invoke functions and
function objects with parameters that don't exactly match.Why (function) cloning?In November and December of 2000, the issue of cloning
vs. reference counting was debated at length and it was decided
that cloning gave more predictable semantics. I won't rehash the
discussion here, but if it cloning is incorrect for a particular
application a reference-counting allocator could be used.How much overhead does a call through boost::function incur?The cost of boost::function can be reasonably
consistently measured at around 20ns +/- 10 ns on a modern >2GHz
platform versus directly inlining the code.However, the performance of your application may benefit
from or be disadvantaged by boost::function
depending on how your C++ optimiser optimises. Similar to a
standard function pointer, differences of order of 10% have been
noted to the benefit or disadvantage of using
boost::function to call a function that contains a
tight loop depending on your compilation circumstances.[Answer provided by Matt Hurd. See ]Miscellaneous NotesBoost.Function vs. Function PointersBoost.Function has several advantages over function pointers, namely:
Boost.Function allows arbitrary compatible function objects to be targets (instead of requiring an exact function signature).Boost.Function may be used with argument-binding and other function object construction libraries.Boost.Function has predictible behavior when an empty function object is called. And, of course, function pointers have several advantages over Boost.Function:
Function pointers are smaller (the size of one pointer instead of three) Function pointers are faster (Boost.Function may require two calls through function pointers) Function pointers are backward-compatible with C libraries. More readable error messages. PerformanceFunction object wrapper size Function object wrappers will be the size of two function pointers plus one function pointer or data pointer (whichever is larger). On common 32-bit platforms, this amounts to 12 bytes per wrapper. Additionally, the function object target will be allocated on the heap.Copying efficiency Copying function object wrappers may require allocating memory for a copy of the function object target. The default allocator may be replaced with a faster custom allocator or one may choose to allow the function object wrappers to only store function object targets by reference (using ref) if the cost of this cloning becomes prohibitive.Invocation efficiency With a properly inlining compiler, an invocation of a function object requires one call through a function pointer. If the call is to a free function pointer, an additional call must be made to that function pointer (unless the compiler has very powerful interprocedural analysis).Combatting virtual function "bloat" The use of virtual functions tends to cause 'code bloat' on many compilers. When a class contains a virtual function, it is necessary to emit an additional function that classifies the type of the object. It has been our experience that these auxiliary functions increase the size of the executable significantly when many boost::function objects are used. In Boost.Function, an alternative but equivalent approach was taken using free functions instead of virtual functions. The Boost.Function object essentially holds two pointers to make a valid target call: a void pointer to the function object it contains and a void pointer to an "invoker" that can call the function object, given the function pointer. This invoker function performs the argument and return value conversions Boost.Function provides. A third pointer points to a free function called the "manager", which handles the cloning and destruction of function objects. The scheme is typesafe because the only functions that actually handle the function object, the invoker and the manager, are instantiated given the type of the function object, so they can safely cast the incoming void pointer (the function object pointer) to the appropriate type.Acknowledgements Many people were involved in the construction of this
library. William Kempf, Jesse Jones and Karl Nelson were all
extremely helpful in isolating an interface and scope for the
library. John Maddock managed the formal review, and many
reviewers gave excellent comments on interface, implementation,
and documentation. Peter Dimov led us to the function
declarator-based syntax.TestsuiteAcceptance testsTestTypeDescriptionIf failing...function_test.cpprunTest the capabilities of the boost::function class template.The boost::function class template may not be usable on your compiler. However, the library may still be usable via the boost::functionN class templates.function_n_test.cpprunTest the capabilities of the boost::functionN class templates.allocator_test.cpprunTest the use of custom allocators.Allocators are ignored by the implementation.stateless_test.cpprunTest the optimization of stateless function objects in the Boost.Function library.The exception-safety and performance guarantees given for stateless function objects may not be met by the implementation.lambda_test.cpprunTest the interaction between Boost.Function and Boost.Lambda.Either Boost.Lambda does not work on the platform, or Boost.Function cannot safely be applied without the use of boost::unlambda.contains_test.cpprunTest the operation of the
target member function and the
equality operators.function_30.cppcompileTest the generation of a Boost.Function function object adaptor accepting 30 arguments.The Boost.Function library may work for function object adaptors of up to 10 parameters, but will be unable to generate adaptors for an arbitrary number of parameters. Failure often indicates an error in the compiler's preprocessor.function_arith_cxx98.cpprunTest the first tutorial example.function_arith_portable.cpprunTest the first tutorial example.sum_avg_cxx98.cpprunTest the second tutorial example.sum_avg_portable.cpprunTest the second tutorial example.mem_fun_cxx98.cpprunTest member function example from tutorial.mem_fun_portable.cpprunTest member function example from tutorial.std_bind_cxx98.cpprunTest standard binders example from tutorial.std_bind_portable.cpprunTest standard binders example from tutorial.function_ref_cxx98.cpprunTest boost::ref example from tutorial.function_ref_portable.cpprunTest boost::ref example from tutorial.Negative testsTestTypeDescriptionIf failing...function_test_fail1.cppcompile-failTest the (incorrect!) use of comparisons between Boost.Function function objects.Intuitive (but incorrect!) code may compile and will give meaningless results.function_test_fail2.cppcompile-failTest the use of an incompatible function object with Boost.FunctionIncorrect code may compile (with potentially unexpected results).JaakkoJärvijarvi at cs tamu edu199920002001200220032004Jaakko JärviGary PowellUse, modification and distribution is 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)Boost.LambdaIn a nutshell
The Boost Lambda Library (BLL in the sequel) is a C++ template
library, which implements form of lambda abstractions for C++.
The term originates from functional programming and lambda calculus, where a lambda abstraction defines an unnamed function.
The primary motivation for the BLL is to provide flexible and
convenient means to define unnamed function objects for STL algorithms.
In explaining what the library is about, a line of code says more than a thousand words; the
following line outputs the elements of some STL container
a separated by spaces:
for_each(a.begin(), a.end(), std::cout << _1 << ' ');
The expression std::cout << _1 << ' ' defines a unary function object.
The variable _1 is the parameter of this function, a placeholder for the actual argument.
Within each iteration of for_each, the function is
called with an element of a as the actual argument.
This actual argument is substituted for the placeholder, and the body of the function is evaluated.
The essence of BLL is letting you define small unnamed function objects, such as the one above, directly on the call site of an STL algorithm.
Getting StartedInstalling the library
The library consists of include files only, hence there is no
installation procedure. The boost include directory
must be on the include path.
There are a number of include files that give different functionality:
lambda/lambda.hpp defines lambda expressions for different C++
operators, see .
lambda/bind.hpp defines bind functions for up to 9 arguments, see .lambda/if.hpp defines lambda function equivalents for if statements and the conditional operator, see (includes lambda.hpp).
lambda/loops.hpp defines lambda function equivalent for looping constructs, see .
lambda/switch.hpp defines lambda function equivalent for the switch statement, see .
lambda/construct.hpp provides tools for writing lambda expressions with constructor, destructor, new and delete invocations, see (includes lambda.hpp).
lambda/casts.hpp provides lambda versions of different casts, as well as sizeof and typeid, see .
lambda/exceptions.hpp gives tools for throwing and catching
exceptions within lambda functions, (includes
lambda.hpp).
lambda/algorithm.hpp and lambda/numeric.hpp (cf. standard algortihm and numeric headers) allow nested STL algorithm invocations, see .
Any other header files in the package are for internal use.
Additionally, the library depends on two other Boost Libraries, the
Tuple and the type_traits libraries, and on the boost/ref.hpp header.
All definitions are placed in the namespace boost::lambda and its subnamespaces.
Conventions used in this documentIn most code examples, we omit the namespace prefixes for names in the std and boost::lambda namespaces.
Implicit using declarations
using namespace std;
using namespace boost::lambda;
are assumed to be in effect.
IntroductionMotivationThe Standard Template Library (STL)
, now part of the C++ Standard Library , is a generic container and algorithm library.
Typically STL algorithms operate on container elements via function objects. These function objects are passed as arguments to the algorithms.
Any C++ construct that can be called with the function call syntax
is a function object.
The STL contains predefined function objects for some common cases (such as plus, less and not1).
As an example, one possible implementation for the standard plus template is:
template <class T> : public binary_function<T, T, T>
struct plus {
T operator()(const T& i, const T& j) const {
return i + j;
}
};
The base class binary_function<T, T, T> contains typedefs for the argument and return types of the function object, which are needed to make the function object adaptable.
In addition to the basic function object classes, such as the one above,
the STL contains binder templates for creating a unary function object from an adaptable binary function object by fixing one of the arguments to a constant value.
For example, instead of having to explicitly write a function object class like:
class plus_1 {
int _i;
public:
plus_1(const int& i) : _i(i) {}
int operator()(const int& j) { return _i + j; }
};
the equivalent functionality can be achieved with the plus template and one of the binder templates (bind1st).
E.g., the following two expressions create function objects with identical functionalities;
when invoked, both return the result of adding 1 to the argument of the function object:
plus_1(1)
bind1st(plus<int>(), 1)
The subexpression plus<int>() in the latter line is a binary function object which computes the sum of two integers, and bind1st invokes this function object partially binding the first argument to 1.
As an example of using the above function object, the following code adds 1 to each element of some container a and outputs the results into the standard output stream cout.
transform(a.begin(), a.end(), ostream_iterator<int>(cout),
bind1st(plus<int>(), 1));
To make the binder templates more generally applicable, the STL contains adaptors for making
pointers or references to functions, and pointers to member functions,
adaptable.
Finally, some STL implementations contain function composition operations as
extensions to the standard .
All these tools aim at one goal: to make it possible to specify
unnamed functions in a call of an STL algorithm,
in other words, to pass code fragments as an argument to a function.
However, this goal is attained only partially.
The simple example above shows that the definition of unnamed functions
with the standard tools is cumbersome.
Complex expressions involving functors, adaptors, binders and
function composition operations tend to be difficult to comprehend.
In addition to this, there are significant restrictions in applying
the standard tools. E.g. the standard binders allow only one argument
of a binary function to be bound; there are no binders for
3-ary, 4-ary etc. functions.
The Boost Lambda Library provides solutions for the problems described above:
Unnamed functions can be created easily with an intuitive syntax.
The above example can be written as:
transform(a.begin(), a.end(), ostream_iterator<int>(cout),
1 + _1);
or even more intuitively:
for_each(a.begin(), a.end(), cout << (1 + _1));
Most of the restrictions in argument binding are removed,
arbitrary arguments of practically any C++ function can be bound.
Separate function composition operations are not needed,
as function composition is supported implicitly.
Introduction to lambda expressions
Lambda expression are common in functional programming languages.
Their syntax varies between languages (and between different forms of lambda calculus), but the basic form of a lambda expressions is:
lambda x1 ... xn.e
A lambda expression defines an unnamed function and consists of:
the parameters of this function: x1 ... xn.
the expression e which computes the value of the function in terms of the parameters x1 ... xn.
A simple example of a lambda expression is
lambda x y.x+y
Applying the lambda function means substituting the formal parameters with the actual arguments:
(lambda x y.x+y) 2 3 = 2 + 3 = 5
In the C++ version of lambda expressions the lambda x1 ... xn part is missing and the formal parameters have predefined names.
In the current version of the library,
there are three such predefined formal parameters,
called placeholders:
_1, _2 and _3.
They refer to the first, second and third argument of the function defined
by the lambda expression.
For example, the C++ version of the definition
lambda x y.x+y
is
_1 + _2
Hence, there is no syntactic keyword for C++ lambda expressions.
The use of a placeholder as an operand implies that the operator invocation is a lambda expression.
However, this is true only for operator invocations.
Lambda expressions containing function calls, control structures, casts etc. require special syntactic constructs.
Most importantly, function calls need to be wrapped inside a bind function.
As an example, consider the lambda expression:
lambda x y.foo(x,y)
Rather than foo(_1, _2), the C++ counterpart for this expression is:
bind(foo, _1, _2)
We refer to this type of C++ lambda expressions as bind expressions.
A lambda expression defines a C++ function object, hence function application syntax is like calling any other function object, for instance: (_1 + _2)(i, j).
Partial function application
A bind expression is in effect a partial function application.
In partial function application, some of the arguments of a function are bound to fixed values.
The result is another function, with possibly fewer arguments.
When called with the unbound arguments, this new function invokes the original function with the merged argument list of bound and unbound arguments.
Terminology
A lambda expression defines a function. A C++ lambda expression concretely constructs a function object, a functor, when evaluated. We use the name lambda functor to refer to such a function object.
Hence, in the terminology adopted here, the result of evaluating a lambda expression is a lambda functor.
Using the library
The purpose of this section is to introduce the basic functionality of the library.
There are quite a lot of exceptions and special cases, but discussion of them is postponed until later sections.
Introductory Examples
In this section we give basic examples of using BLL lambda expressions in STL algorithm invocations.
We start with some simple expressions and work up.
First, we initialize the elements of a container, say, a list, to the value 1:
list<int> v(10);
for_each(v.begin(), v.end(), _1 = 1);
The expression _1 = 1 creates a lambda functor which assigns the value 1 to every element in v.
Strictly taken, the C++ standard defines for_each as a non-modifying sequence operation, and the function object passed to for_each should not modify its argument.
The requirements for the arguments of for_each are unnecessary strict, since as long as the iterators are mutable, for_each accepts a function object that can have side-effects on their argument.
Nevertheless, it is straightforward to provide another function template with the functionality ofstd::for_each but more fine-grained requirements for its arguments.
Next, we create a container of pointers and make them point to the elements in the first container v:
vector<int*> vp(10);
transform(v.begin(), v.end(), vp.begin(), &_1);
The expression &_1 creates a function object for getting the address of each element in v.
The addresses get assigned to the corresponding elements in vp.
The next code fragment changes the values in v.
For each element, the function foo is called.
The original value of the element is passed as an argument to foo.
The result of foo is assigned back to the element:
int foo(int);
for_each(v.begin(), v.end(), _1 = bind(foo, _1));
The next step is to sort the elements of vp:
sort(vp.begin(), vp.end(), *_1 > *_2);
In this call to sort, we are sorting the elements by their contents in descending order.
Finally, the following for_each call outputs the sorted content of vp separated by line breaks:
for_each(vp.begin(), vp.end(), cout << *_1 << '\n');
Note that a normal (non-lambda) expression as subexpression of a lambda expression is evaluated immediately.
This may cause surprises.
For instance, if the previous example is rewritten as
for_each(vp.begin(), vp.end(), cout << '\n' << *_1);
the subexpression cout << '\n' is evaluated immediately and the effect is to output a single line break, followed by the elements of vp.
The BLL provides functions constant and var to turn constants and, respectively, variables into lambda expressions, and can be used to prevent the immediate evaluation of subexpressions:
for_each(vp.begin(), vp.end(), cout << constant('\n') << *_1);
These functions are described more thoroughly in Parameter and return types of lambda functors
During the invocation of a lambda functor, the actual arguments are substituted for the placeholders.
The placeholders do not dictate the type of these actual arguments.
The basic rule is that a lambda function can be called with arguments of any types, as long as the lambda expression with substitutions performed is a valid C++ expression.
As an example, the expression
_1 + _2 creates a binary lambda functor.
It can be called with two objects of any types A and B for which operator+(A,B) is defined (and for which BLL knows the return type of the operator, see below).
C++ lacks a mechanism to query a type of an expression.
However, this precise mechanism is crucial for the implementation of C++ lambda expressions.
Consequently, BLL includes a somewhat complex type deduction system which uses a set of traits classes for deducing the resulting type of lambda functions.
It handles expressions where the operands are of built-in types and many of the expressions with operands of standard library types.
Many of the user defined types are covered as well, particularly if the user defined operators obey normal conventions in defining the return types.
There are, however, cases when the return type cannot be deduced. For example, suppose you have defined:
C operator+(A, B);
The following lambda function invocation fails, since the return type cannot be deduced:
A a; B b; (_1 + _2)(a, b);
There are two alternative solutions to this.
The first is to extend the BLL type deduction system to cover your own types (see ).
The second is to use a special lambda expression (ret) which defines the return type in place (see ):
A a; B b; ret<C>(_1 + _2)(a, b);
For bind expressions, the return type can be defined as a template argument of the bind function as well:
bind<int>(foo, _1, _2);About actual arguments to lambda functorsA general restriction for the actual arguments is that they cannot be non-const rvalues.
For example:
int i = 1; int j = 2;
(_1 + _2)(i, j); // ok
(_1 + _2)(1, 2); // error (!)
This restriction is not as bad as it may look.
Since the lambda functors are most often called inside STL-algorithms,
the arguments originate from dereferencing iterators and the dereferencing operators seldom return rvalues.
And for the cases where they do, there are workarounds discussed in
.
Storing bound arguments in lambda functions
By default, temporary const copies of the bound arguments are stored
in the lambda functor.
This means that the value of a bound argument is fixed at the time of the
creation of the lambda function and remains constant during the lifetime
of the lambda function object.
For example:
int i = 1;
(_1 = 2, _1 + i)(i);
The comma operator is overloaded to combine lambda expressions into a sequence;
the resulting unary lambda functor first assigns 2 to its argument,
then adds the value of i to it.
The value of the expression in the last line is 3, not 4.
In other words, the lambda expression that is created is
lambda x.(x = 2, x + 1) rather than
lambda x.(x = 2, x + i).
As said, this is the default behavior for which there are exceptions.
The exact rules are as follows:
The programmer can control the storing mechanism with ref
and cref wrappers .
Wrapping an argument with ref, or cref,
instructs the library to store the argument as a reference,
or as a reference to const respectively.
For example, if we rewrite the previous example and wrap the variable
i with ref,
we are creating the lambda expression lambda x.(x = 2, x + i)
and the value of the expression in the last line will be 4:
i = 1;
(_1 = 2, _1 + ref(i))(i);
Note that ref and cref are different
from var and constant.
While the latter ones create lambda functors, the former do not.
For example:
int i;
var(i) = 1; // ok
ref(i) = 1; // not ok, ref(i) is not a lambda functor
The functions ref and cref mostly
exist for historical reasons,
and ref can always
be replaced with var, and cref with
constant_ref.
See for details.
The ref and cref functions are
general purpose utility functions in Boost, and hence defined directly
in the boost namespace.
Array types cannot be copied, they are thus stored as const reference by default.
For some expressions it makes more sense to store the arguments as references.
For example, the obvious intention of the lambda expression
i += _1 is that calls to the lambda functor affect the
value of the variable i,
rather than some temporary copy of it.
As another example, the streaming operators take their leftmost argument
as non-const references.
The exact rules are:
The left argument of compound assignment operators (+=, *=, etc.) are stored as references to non-const.If the left argument of << or >> operator is derived from an instantiation of basic_ostream or respectively from basic_istream, the argument is stored as a reference to non-const.
For all other types, the argument is stored as a copy.
In pointer arithmetic expressions, non-const array types are stored as non-const references.
This is to prevent pointer arithmetic making non-const arrays const.
Lambda expressions in details
This section describes different categories of lambda expressions in details.
We devote a separate section for each of the possible forms of a lambda expression.
Placeholders
The BLL defines three placeholder types: placeholder1_type, placeholder2_type and placeholder3_type.
BLL has a predefined placeholder variable for each placeholder type: _1, _2 and _3.
However, the user is not forced to use these placeholders.
It is easy to define placeholders with alternative names.
This is done by defining new variables of placeholder types.
For example:
boost::lambda::placeholder1_type X;
boost::lambda::placeholder2_type Y;
boost::lambda::placeholder3_type Z;
With these variables defined, X += Y * Z is equivalent to _1 += _2 * _3.
The use of placeholders in the lambda expression determines whether the resulting function is nullary, unary, binary or 3-ary.
The highest placeholder index is decisive. For example:
_1 + 5 // unary
_1 * _1 + _1 // unary
_1 + _2 // binary
bind(f, _1, _2, _3) // 3-ary
_3 + 10 // 3-ary
Note that the last line creates a 3-ary function, which adds 10 to its third argument.
The first two arguments are discarded.
Furthermore, lambda functors only have a minimum arity.
One can always provide more arguments (up the number of supported placeholders)
that is really needed.
The remaining arguments are just discarded.
For example:
int i, j, k;
_1(i, j, k) // returns i, discards j and k
(_2 + _2)(i, j, k) // returns j+j, discards i and k
See
for the design rationale behind this
functionality.
In addition to these three placeholder types, there is also a fourth placeholder type placeholderE_type.
The use of this placeholder is defined in describing exception handling in lambda expressions.
When an actual argument is supplied for a placeholder, the parameter passing mode is always by reference.
This means that any side-effects to the placeholder are reflected to the actual argument.
For example:
int i = 1;
(_1 += 2)(i); // i is now 3
(++_1, cout << _1)(i) // i is now 4, outputs 4
Operator expressions
The basic rule is that any C++ operator invocation with at least one argument being a lambda expression is itself a lambda expression.
Almost all overloadable operators are supported.
For example, the following is a valid lambda expression:
cout << _1, _2[_3] = _1 && false
However, there are some restrictions that originate from the C++ operator overloading rules, and some special cases.
Operators that cannot be overloaded
Some operators cannot be overloaded at all (::, ., .*).
For some operators, the requirements on return types prevent them to be overloaded to create lambda functors.
These operators are ->., ->, new, new[], delete, delete[] and ?: (the conditional operator).
Assignment and subscript operators
These operators must be implemented as class members.
Consequently, the left operand must be a lambda expression. For example:
int i;
_1 = i; // ok
i = _1; // not ok. i is not a lambda expression
There is a simple solution around this limitation, described in .
In short,
the left hand argument can be explicitly turned into a lambda functor by wrapping it with a special var function:
var(i) = _1; // ok
Logical operators
Logical operators obey the short-circuiting evaluation rules. For example, in the following code, i is never incremented:
bool flag = true; int i = 0;
(_1 || ++_2)(flag, i);
Comma operator
Comma operator is the statement separator in lambda expressions.
Since comma is also the separator between arguments in a function call, extra parenthesis are sometimes needed:
for_each(a.begin(), a.end(), (++_1, cout << _1));
Without the extra parenthesis around ++_1, cout << _1, the code would be interpreted as an attempt to call for_each with four arguments.
The lambda functor created by the comma operator adheres to the C++ rule of always evaluating the left operand before the right one.
In the above example, each element of a is first incremented, then written to the stream.
Function call operator
The function call operators have the effect of evaluating the lambda
functor.
Calls with too few arguments lead to a compile time error.
Member pointer operator
The member pointer operator operator->* can be overloaded freely.
Hence, for user defined types, member pointer operator is no special case.
The built-in meaning, however, is a somewhat more complicated case.
The built-in member pointer operator is applied if the left argument is a pointer to an object of some class A, and the right hand argument is a pointer to a member of A, or a pointer to a member of a class from which A derives.
We must separate two cases:
The right hand argument is a pointer to a data member.
In this case the lambda functor simply performs the argument substitution and calls the built-in member pointer operator, which returns a reference to the member pointed to.
For example:
struct A { int d; };
A* a = new A();
...
(a ->* &A::d); // returns a reference to a->d
(_1 ->* &A::d)(a); // likewise
The right hand argument is a pointer to a member function.
For a built-in call like this, the result is kind of a delayed member function call.
Such an expression must be followed by a function argument list, with which the delayed member function call is performed.
For example:
struct B { int foo(int); };
B* b = new B();
...
(b ->* &B::foo) // returns a delayed call to b->foo
// a function argument list must follow
(b ->* &B::foo)(1) // ok, calls b->foo(1)
(_1 ->* &B::foo)(b); // returns a delayed call to b->foo,
// no effect as such
(_1 ->* &B::foo)(b)(1); // calls b->foo(1)
Bind expressions
Bind expressions can have two forms:
bind(target-function, bind-argument-list)
bind(target-member-function, object-argument, bind-argument-list)
A bind expression delays the call of a function.
If this target function is n-ary, then the bind-argument-list must contain n arguments as well.
In the current version of the BLL, 0 <= n <= 9 must hold.
For member functions, the number of arguments must be at most 8, as the object argument takes one argument position.
Basically, the
bind-argument-list must be a valid argument list for the target function, except that any argument can be replaced with a placeholder, or more generally, with a lambda expression.
Note that also the target function can be a lambda expression.
The result of a bind expression is either a nullary, unary, binary or 3-ary function object depending on the use of placeholders in the bind-argument-list (see ).
The return type of the lambda functor created by the bind expression can be given as an explicitly specified template parameter, as in the following example:
bind<RET>(target-function, bind-argument-list)
This is only necessary if the return type of the target function cannot be deduced.
The following sections describe the different types of bind expressions.
Function pointers or references as targetsThe target function can be a pointer or a reference to a function and it can be either bound or unbound. For example:
X foo(A, B, C); A a; B b; C c;
bind(foo, _1, _2, c)(a, b);
bind(&foo, _1, _2, c)(a, b);
bind(_1, a, b, c)(foo);
The return type deduction always succeeds with this type of bind expressions.
Note, that in C++ it is possible to take the address of an overloaded function only if the address is assigned to, or used as an initializer of, a variable, the type of which solves the amibiguity, or if an explicit cast expression is used.
This means that overloaded functions cannot be used in bind expressions directly, e.g.:
void foo(int);
void foo(float);
int i;
...
bind(&foo, _1)(i); // error
...
void (*pf1)(int) = &foo;
bind(pf1, _1)(i); // ok
bind(static_cast<void(*)(int)>(&foo), _1)(i); // ok
Member functions as targets
The syntax for using pointers to member function in bind expression is:
bind(target-member-function, object-argument, bind-argument-list)
The object argument can be a reference or pointer to the object, the BLL supports both cases with a uniform interface:
bool A::foo(int) const;
A a;
vector<int> ints;
...
find_if(ints.begin(), ints.end(), bind(&A::foo, a, _1));
find_if(ints.begin(), ints.end(), bind(&A::foo, &a, _1));
Similarly, if the object argument is unbound, the resulting lambda functor can be called both via a pointer or a reference:
bool A::foo(int);
list<A> refs;
list<A*> pointers;
...
find_if(refs.begin(), refs.end(), bind(&A::foo, _1, 1));
find_if(pointers.begin(), pointers.end(), bind(&A::foo, _1, 1));
Even though the interfaces are the same, there are important semantic differences between using a pointer or a reference as the object argument.
The differences stem from the way bind-functions take their parameters, and how the bound parameters are stored within the lambda functor.
The object argument has the same parameter passing and storing mechanism as any other bind argument slot (see ); it is passed as a const reference and stored as a const copy in the lambda functor.
This creates some asymmetry between the lambda functor and the original member function, and between seemingly similar lambda functors. For example:
class A {
int i; mutable int j;
public:
A(int ii, int jj) : i(ii), j(jj) {};
void set_i(int x) { i = x; };
void set_j(int x) const { j = x; };
};
When a pointer is used, the behavior is what the programmer might expect:
A a(0,0); int k = 1;
bind(&A::set_i, &a, _1)(k); // a.i == 1
bind(&A::set_j, &a, _1)(k); // a.j == 1
Even though a const copy of the object argument is stored, the original object a is still modified.
This is since the object argument is a pointer, and the pointer is copied, not the object it points to.
When we use a reference, the behaviour is different:
A a(0,0); int k = 1;
bind(&A::set_i, a, _1)(k); // error; a const copy of a is stored.
// Cannot call a non-const function set_i
bind(&A::set_j, a, _1)(k); // a.j == 0, as a copy of a is modified
To prevent the copying from taking place, one can use the ref or cref wrappers (var and constant_ref would do as well):
bind(&A::set_i, ref(a), _1)(k); // a.j == 1
bind(&A::set_j, cref(a), _1)(k); // a.j == 1
Note that the preceding discussion is relevant only for bound arguments.
If the object argument is unbound, the parameter passing mode is always by reference.
Hence, the argument a is not copied in the calls to the two lambda functors below:
A a(0,0);
bind(&A::set_i, _1, 1)(a); // a.i == 1
bind(&A::set_j, _1, 1)(a); // a.j == 1
Member variables as targets
A pointer to a member variable is not really a function, but
the first argument to the bind function can nevertheless
be a pointer to a member variable.
Invoking such a bind expression returns a reference to the data member.
For example:
struct A { int data; };
A a;
bind(&A::data, _1)(a) = 1; // a.data == 1
The cv-qualifiers of the object whose member is accessed are respected.
For example, the following tries to write into a const location:
const A ca = a;
bind(&A::data, _1)(ca) = 1; // error
Function objects as targets
Function objects, that is, class objects which have the function call
operator defined, can be used as target functions.
In general, BLL cannot deduce the return type of an arbitrary function object.
However, there are two methods for giving BLL this capability for a certain
function object class.
The result_type typedef
The BLL supports the standard library convention of declaring the return type
of a function object with a member typedef named result_type in the
function object class.
Here is a simple example:
struct A {
typedef B result_type;
B operator()(X, Y, Z);
};
If a function object does not define a result_type typedef,
the method described below (sig template)
is attempted to resolve the return type of the
function object. If a function object defines both result_type
and sig, result_type takes precedence.
The sig template
Another mechanism that make BLL aware of the return type(s) of a function object is defining
member template struct
sig<Args> with a typedef
type that specifies the return type.
Here is a simple example:
struct A {
template <class Args> struct sig { typedef B type; }
B operator()(X, Y, Z);
};
The template argument Args is a
tuple (or more precisely a cons list)
type , where the first element
is the function
object type itself, and the remaining elements are the types of
the arguments, with which the function object is being called.
This may seem overly complex compared to defining the result_type typedef.
Howver, there are two significant restrictions with using just a simple
typedef to express the return type:
If the function object defines several function call operators, there is no way to specify different result types for them.
If the function call operator is a template, the result type may
depend on the template parameters.
Hence, the typedef ought to be a template too, which the C++ language
does not support.
The following code shows an example, where the return type depends on the type
of one of the arguments, and how that dependency can be expressed with the
sig template:
struct A {
// the return type equals the third argument type:
template<class T1, class T2, class T3>
T3 operator()(const T1& t1, const T2& t2, const T3& t3) const;
template <class Args>
class sig {
// get the third argument type (4th element)
typedef typename
boost::tuples::element<3, Args>::type T3;
public:
typedef typename
boost::remove_cv<T3>::type type;
};
};
The elements of the Args tuple are always
non-reference types.
Moreover, the element types can have a const or volatile qualifier
(jointly referred to as cv-qualifiers), or both.
This is since the cv-qualifiers in the arguments can affect the return type.
The reason for including the potentially cv-qualified function object
type itself into the Args tuple, is that the function
object class can contain both const and non-const (or volatile, even
const volatile) function call operators, and they can each have a different
return type.
The sig template can be seen as a
meta-function that maps the argument type tuple to
the result type of the call made with arguments of the types in the tuple.
As the example above demonstrates, the template can end up being somewhat
complex.
Typical tasks to be performed are the extraction of the relevant types
from the tuple, removing cv-qualifiers etc.
See the Boost type_traits and
Tuple libraries
for tools that can aid in these tasks.
The sig templates are a refined version of a similar
mechanism first introduced in the FC++ library
.
Overriding the deduced return type
The return type deduction system may not be able to deduce the return types of some user defined operators or bind expressions with class objects.
A special lambda expression type is provided for stating the return type explicitly and overriding the deduction system.
To state that the return type of the lambda functor defined by the lambda expression e is T, you can write:
ret<T>(e);
The effect is that the return type deduction is not performed for the lambda expression e at all, but instead, T is used as the return type.
Obviously T cannot be an arbitrary type, the true result of the lambda functor must be implicitly convertible to T.
For example:
A a; B b;
C operator+(A, B);
int operator*(A, B);
...
ret<D>(_1 + _2)(a, b); // error (C cannot be converted to D)
ret<C>(_1 + _2)(a, b); // ok
ret<float>(_1 * _2)(a, b); // ok (int can be converted to float)
...
struct X {
Y operator(int)();
};
...
X x; int i;
bind(x, _1)(i); // error, return type cannot be deduced
ret<Y>(bind(x, _1))(i); // ok
For bind expressions, there is a short-hand notation that can be used instead of ret.
The last line could alternatively be written as:
bind<Z>(x, _1)(i);
This feature is modeled after the Boost Bind library .
Note that within nested lambda expressions,
the ret must be used at each subexpression where
the deduction would otherwise fail.
For example:
A a; B b;
C operator+(A, B); D operator-(C);
...
ret<D>( - (_1 + _2))(a, b); // error
ret<D>( - ret<C>(_1 + _2))(a, b); // ok
If you find yourself using ret repeatedly with the same types, it is worth while extending the return type deduction (see ).
Nullary lambda functors and ret
As stated above, the effect of ret is to prevent the return type deduction to be performed.
However, there is an exception.
Due to the way the C++ template instantiation works, the compiler is always forced to instantiate the return type deduction templates for zero-argument lambda functors.
This introduces a slight problem with ret, best described with an example:
struct F { int operator()(int i) const; };
F f;
...
bind(f, _1); // fails, cannot deduce the return type
ret<int>(bind(f, _1)); // ok
...
bind(f, 1); // fails, cannot deduce the return type
ret<int>(bind(f, 1)); // fails as well!
The BLL cannot deduce the return types of the above bind calls, as F does not define the typedef result_type.
One would expect ret to fix this, but for the nullary lambda functor that results from a bind expression (last line above) this does not work.
The return type deduction templates are instantiated, even though it would not be necessary and the result is a compilation error.
The solution to this is not to use the ret function, but rather define the return type as an explicitly specified template parameter in the bind call:
bind<int>(f, 1); // ok
The lambda functors created with
ret<T>(bind(arg-list)) and
bind<T>(arg-list) have the exact same functionality —
apart from the fact that for some nullary lambda functors the former does not work while the latter does.
Delaying constants and variables
The unary functions constant,
constant_ref and var turn their argument into a lambda functor, that implements an identity mapping.
The former two are for constants, the latter for variables.
The use of these delayed constants and variables is sometimes necessary due to the lack of explicit syntax for lambda expressions.
For example:
for_each(a.begin(), a.end(), cout << _1 << ' ');
for_each(a.begin(), a.end(), cout << ' ' << _1);
The first line outputs the elements of a separated by spaces, while the second line outputs a space followed by the elements of a without any separators.
The reason for this is that neither of the operands of
cout << ' ' is a lambda expression, hence cout << ' ' is evaluated immediately.
To delay the evaluation of cout << ' ', one of the operands must be explicitly marked as a lambda expression.
This is accomplished with the constant function:
for_each(a.begin(), a.end(), cout << constant(' ') << _1);
The call constant(' ') creates a nullary lambda functor which stores the character constant ' '
and returns a reference to it when invoked.
The function constant_ref is similar, except that it
stores a constant reference to its argument.
The constant and consant_ref are only
needed when the operator call has side effects, like in the above example.
Sometimes we need to delay the evaluation of a variable.
Suppose we wanted to output the elements of a container in a numbered list:
int index = 0;
for_each(a.begin(), a.end(), cout << ++index << ':' << _1 << '\n');
for_each(a.begin(), a.end(), cout << ++var(index) << ':' << _1 << '\n');
The first for_each invocation does not do what we want; index is incremented only once, and its value is written into the output stream only once.
By using var to make index a lambda expression, we get the desired effect.
In sum, var(x) creates a nullary lambda functor,
which stores a reference to the variable x.
When the lambda functor is invoked, a reference to x is returned.
Naming delayed constants and variables
It is possible to predefine and name a delayed variable or constant outside a lambda expression.
The templates var_type, constant_type
and constant_ref_type serve for this purpose.
They are used as:
var_type<T>::type delayed_i(var(i));
constant_type<T>::type delayed_c(constant(c));
The first line defines the variable delayed_i which is a delayed version of the variable i of type T.
Analogously, the second line defines the constant delayed_c as a delayed version of the constant c.
For example:
int i = 0; int j;
for_each(a.begin(), a.end(), (var(j) = _1, _1 = var(i), var(i) = var(j)));
is equivalent to:
int i = 0; int j;
var_type<int>::type vi(var(i)), vj(var(j));
for_each(a.begin(), a.end(), (vj = _1, _1 = vi, vi = vj));
Here is an example of naming a delayed constant:
constant_type<char>::type space(constant(' '));
for_each(a.begin(),a.end(), cout << space << _1);
About assignment and subscript operators
As described in , assignment and subscripting operators are always defined as member functions.
This means, that for expressions of the form
x = y or x[y] to be interpreted as lambda expressions, the left-hand operand x must be a lambda expression.
Consequently, it is sometimes necessary to use var for this purpose.
We repeat the example from :
int i;
i = _1; // error
var(i) = _1; // ok
Note that the compound assignment operators +=, -= etc. can be defined as non-member functions, and thus they are interpreted as lambda expressions even if only the right-hand operand is a lambda expression.
Nevertheless, it is perfectly ok to delay the left operand explicitly.
For example, i += _1 is equivalent to var(i) += _1.
Lambda expressions for control structures
BLL defines several functions to create lambda functors that represent control structures.
They all take lambda functors as parameters and return void.
To start with an example, the following code outputs all even elements of some container a:
for_each(a.begin(), a.end(),
if_then(_1 % 2 == 0, cout << _1));
The BLL supports the following function templates for control structures:
if_then(condition, then_part)
if_then_else(condition, then_part, else_part)
if_then_else_return(condition, then_part, else_part)
while_loop(condition, body)
while_loop(condition) // no body case
do_while_loop(condition, body)
do_while_loop(condition) // no body case
for_loop(init, condition, increment, body)
for_loop(init, condition, increment) // no body case
switch_statement(...)
The return types of all control construct lambda functor is
void, except for if_then_else_return,
which wraps a call to the conditional operator
condition ? then_part : else_part
The return type rules for this operator are somewhat complex.
Basically, if the branches have the same type, this type is the return type.
If the type of the branches differ, one branch, say of type
A, must be convertible to the other branch,
say of type B.
In this situation, the result type is B.
Further, if the common type is an lvalue, the return type will be an lvalue
too.
Delayed variables tend to be commonplace in control structure lambda expressions.
For instance, here we use the var function to turn the arguments of for_loop into lambda expressions.
The effect of the code is to add 1 to each element of a two-dimensional array:
int a[5][10]; int i;
for_each(a, a+5,
for_loop(var(i)=0, var(i)<10, ++var(i),
_1[var(i)] += 1));
The BLL supports an alternative syntax for control expressions, suggested
by Joel de Guzmann.
By overloading the operator[] we can
get a closer resemblance with the built-in control structures:
if_(condition)[then_part]
if_(condition)[then_part].else_[else_part]
while_(condition)[body]
do_[body].while_(condition)
for_(init, condition, increment)[body]
For example, using this syntax the if_then example above
can be written as:
for_each(a.begin(), a.end(),
if_(_1 % 2 == 0)[ cout << _1 ])
As more experience is gained, we may end up deprecating one or the other
of these syntaces.
Switch statement
The lambda expressions for switch control structures are more complex since the number of cases may vary.
The general form of a switch lambda expression is:
switch_statement(condition,
case_statement<label>(lambda expression),
case_statement<label>(lambda expression),
...
default_statement(lambda expression)
)
The condition argument must be a lambda expression that creates a lambda functor with an integral return type.
The different cases are created with the case_statement functions, and the optional default case with the default_statement function.
The case labels are given as explicitly specified template arguments to case_statement functions and
break statements are implicitly part of each case.
For example, case_statement<1>(a), where a is some lambda functor, generates the code:
case 1:
evaluate lambda functor a;
break;
The switch_statement function is specialized for up to 9 case statements.
As a concrete example, the following code iterates over some container v and ouptuts zero for each 0, one for each 1, and other: n for any other value n.
Note that another lambda expression is sequenced after the switch_statement to output a line break after each element:
std::for_each(v.begin(), v.end(),
(
switch_statement(
_1,
case_statement<0>(std::cout << constant("zero")),
case_statement<1>(std::cout << constant("one")),
default_statement(cout << constant("other: ") << _1)
),
cout << constant("\n")
)
);
Exceptions
The BLL provides lambda functors that throw and catch exceptions.
Lambda functors for throwing exceptions are created with the unary function throw_exception.
The argument to this function is the exception to be thrown, or a lambda functor which creates the exception to be thrown.
A lambda functor for rethrowing exceptions is created with the nullary rethrow function.
Lambda expressions for handling exceptions are somewhat more complex.
The general form of a lambda expression for try catch blocks is as follows:
try_catch(
lambda expression,
catch_exception<type>(lambda expression),
catch_exception<type>(lambda expression),
...
catch_all(lambda expression)
)
The first lambda expression is the try block.
Each catch_exception defines a catch block where the
explicitly specified template argument defines the type of the exception
to catch.
The lambda expression within the catch_exception defines
the actions to take if the exception is caught.
Note that the resulting exception handlers catch the exceptions as
references, i.e., catch_exception<T>(...)
results in the catch block:
catch(T& e) { ... }
The last catch block can alternatively be a call to
catch_exception<type>
or to
catch_all, which is the lambda expression equivalent to
catch(...).
The demonstrates the use of the BLL
exception handling tools.
The first handler catches exceptions of type foo_exception.
Note the use of _1 placeholder in the body of the handler.
The second handler shows how to throw exceptions, and demonstrates the
use of the exception placeholder_e.
It is a special placeholder, which refers to the caught exception object
within the handler body.
Here we are handling an exception of type std::exception,
which carries a string explaining the cause of the exception.
This explanation can be queried with the zero-argument member
function what.
The expression
bind(&std::exception::what, _e) creates the lambda
function for making that call.
Note that _e cannot be used outside of an exception handler lambda expression.
The last line of the second handler constructs a new exception object and
throws that with throw exception.
Constructing and destructing objects within lambda expressions is
explained in
Finally, the third handler (catch_all) demonstrates
rethrowing exceptions.
Throwing and handling exceptions in lambda expressions.
for_each(
a.begin(), a.end(),
try_catch(
bind(foo, _1), // foo may throw
catch_exception<foo_exception>(
cout << constant("Caught foo_exception: ")
<< "foo was called with argument = " << _1
),
catch_exception<std::exception>(
cout << constant("Caught std::exception: ")
<< bind(&std::exception::what, _e),
throw_exception(bind(constructor<bar_exception>(), _1)))
),
catch_all(
(cout << constant("Unknown"), rethrow())
)
)
);
Construction and destruction
Operators new and delete can be
overloaded, but their return types are fixed.
Particularly, the return types cannot be lambda functors,
which prevents them to be overloaded for lambda expressions.
It is not possible to take the address of a constructor,
hence constructors cannot be used as target functions in bind expressions.
The same is true for destructors.
As a way around these constraints, BLL defines wrapper classes for
new and delete calls,
as well as for constructors and destructors.
Instances of these classes are function objects, that can be used as
target functions of bind expressions.
For example:
int* a[10];
for_each(a, a+10, _1 = bind(new_ptr<int>()));
for_each(a, a+10, bind(delete_ptr(), _1));
The new_ptr<int>() expression creates
a function object that calls new int() when invoked,
and wrapping that inside bind makes it a lambda functor.
In the same way, the expression delete_ptr() creates
a function object that invokes delete on its argument.
Note that new_ptr<T>()
can take arguments as well.
They are passed directly to the constructor invocation and thus allow
calls to constructors which take arguments.
As an example of constructor calls in lambda expressions,
the following code reads integers from two containers x
and y,
constructs pairs out of them and inserts them into a third container:
vector<pair<int, int> > v;
transform(x.begin(), x.end(), y.begin(), back_inserter(v),
bind(constructor<pair<int, int> >(), _1, _2));
lists all the function
objects related to creating and destroying objects,
showing the expression to create and call the function object,
and the effect of evaluating that expression.
Construction and destruction related function objects.Function object callWrapped expressionconstructor<T>()(arg_list)T(arg_list)destructor()(a)a.~A(), where a is of type Adestructor()(pa)pa->~A(), where pa is of type A*new_ptr<T>()(arg_list)new T(arg_list)new_array<T>()(sz)new T[sz]delete_ptr()(p)delete pdelete_array()(p)delete p[]
Special lambda expressionsPreventing argument substitution
When a lambda functor is called, the default behavior is to substitute
the actual arguments for the placeholders within all subexpressions.
This section describes the tools to prevent the substitution and
evaluation of a subexpression, and explains when these tools should be used.
The arguments to a bind expression can be arbitrary lambda expressions,
e.g., other bind expressions.
For example:
int foo(int); int bar(int);
...
int i;
bind(foo, bind(bar, _1)(i);
The last line makes the call foo(bar(i));
Note that the first argument in a bind expression, the target function,
is no exception, and can thus be a bind expression too.
The innermost lambda functor just has to return something that can be used
as a target function: another lambda functor, function pointer,
pointer to member function etc.
For example, in the following code the innermost lambda functor makes
a selection between two functions, and returns a pointer to one of them:
int add(int a, int b) { return a+b; }
int mul(int a, int b) { return a*b; }
int(*)(int, int) add_or_mul(bool x) {
return x ? add : mul;
}
bool condition; int i; int j;
...
bind(bind(&add_or_mul, _1), _2, _3)(condition, i, j);
UnlambdaA nested bind expression may occur inadvertently,
if the target function is a variable with a type that depends on a
template parameter.
Typically the target function could be a formal parameter of a
function template.
In such a case, the programmer may not know whether the target function is a lambda functor or not.
Consider the following function template:
template<class F>
int nested(const F& f) {
int x;
...
bind(f, _1)(x);
...
}
Somewhere inside the function the formal parameter
f is used as a target function in a bind expression.
In order for this bind call to be valid,
f must be a unary function.
Suppose the following two calls to nested are made:
int foo(int);
int bar(int, int);
nested(&foo);
nested(bind(bar, 1, _1));
Both are unary functions, or function objects, with appropriate argument
and return types, but the latter will not compile.
In the latter call, the bind expression inside nested
will become:
bind(bind(bar, 1, _1), _1)
When this is invoked with x,
after substituitions we end up trying to call
bar(1, x)(x)
which is an error.
The call to bar returns int,
not a unary function or function object.
In the example above, the intent of the bind expression in the
nested function is to treat f
as an ordinary function object, instead of a lambda functor.
The BLL provides the function template unlambda to
express this: a lambda functor wrapped inside unlambda
is not a lambda functor anymore, and does not take part into the
argument substitution process.
Note that for all other argument types unlambda is
an identity operation, except for making non-const objects const.
Using unlambda, the nested
function is written as:
template<class F>
int nested(const F& f) {
int x;
...
bind(unlambda(f), _1)(x);
...
}
Protect
The protect function is related to unlambda.
It is also used to prevent the argument substitution taking place,
but whereas unlambda turns a lambda functor into
an ordinary function object for good, protect does
this temporarily, for just one evaluation round.
For example:
int x = 1, y = 10;
(_1 + protect(_1 + 2))(x)(y);
The first call substitutes x for the leftmost
_1, and results in another lambda functor
x + (_1 + 2), which after the call with
y becomes x + (y + 2),
and thus finally 13.
Primary motivation for including protect into the library,
was to allow nested STL algorithm invocations
().
Rvalues as actual arguments to lambda functors
Actual arguments to the lambda functors cannot be non-const rvalues.
This is due to a deliberate design decision: either we have this restriction,
or there can be no side-effects to the actual arguments.
There are ways around this limitation.
We repeat the example from section
and list the
different solutions:
int i = 1; int j = 2;
(_1 + _2)(i, j); // ok
(_1 + _2)(1, 2); // error (!)
If the rvalue is of a class type, the return type of the function that
creates the rvalue should be defined as const.
Due to an unfortunate language restriction this does not work for
built-in types, as built-in rvalues cannot be const qualified.
If the lambda function call is accessible, the make_const
function can be used to constify the rvalue. E.g.:
(_1 + _2)(make_const(1), make_const(2)); // ok
Commonly the lambda function call site is inside a standard algorithm
function template, preventing this solution to be used.
If neither of the above is possible, the lambda expression can be wrapped
in a const_parameters function.
It creates another type of lambda functor, which takes its arguments as
const references. For example:
const_parameters(_1 + _2)(1, 2); // ok
Note that const_parameters makes all arguments const.
Hence, in the case were one of the arguments is a non-const rvalue,
and another argument needs to be passed as a non-const reference,
this approach cannot be used.
If none of the above is possible, there is still one solution,
which unfortunately can break const correctness.
The solution is yet another lambda functor wrapper, which we have named
break_const to alert the user of the potential dangers
of this function.
The break_const function creates a lambda functor that
takes its arguments as const, and casts away constness prior to the call
to the original wrapped lambda functor.
For example:
int i;
...
(_1 += _2)(i, 2); // error, 2 is a non-const rvalue
const_parameters(_1 += _2)(i, 2); // error, i becomes const
break_const(_1 += _2)(i, 2); // ok, but dangerous
Note, that the results of break_const or
const_parameters are not lambda functors,
so they cannot be used as subexpressions of lambda expressions. For instance:
break_const(_1 + _2) + _3; // fails.
const_parameters(_1 + _2) + _3; // fails.
However, this kind of code should never be necessary,
since calls to sub lambda functors are made inside the BLL,
and are not affected by the non-const rvalue problem.
Casts, sizeof and typeid
Cast expressions
The BLL defines its counterparts for the four cast expressions
static_cast, dynamic_cast,
const_cast and reinterpret_cast.
The BLL versions of the cast expressions have the prefix
ll_.
The type to cast to is given as an explicitly specified template argument,
and the sole argument is the expression from which to perform the cast.
If the argument is a lambda functor, the lambda functor is evaluated first.
For example, the following code uses ll_dynamic_cast
to count the number of derived instances in the container
a:
class base {};
class derived : public base {};
vector<base*> a;
...
int count = 0;
for_each(a.begin(), a.end(),
if_then(ll_dynamic_cast<derived*>(_1), ++var(count)));
Sizeof and typeid
The BLL counterparts for these expressions are named
ll_sizeof and ll_typeid.
Both take one argument, which can be a lambda expression.
The lambda functor created wraps the sizeof or
typeid call, and when the lambda functor is called
the wrapped operation is performed.
For example:
vector<base*> a;
...
for_each(a.begin(), a.end(),
cout << bind(&type_info::name, ll_typeid(*_1)));
Here ll_typeid creates a lambda functor for
calling typeid for each element.
The result of a typeid call is an instance of
the type_info class, and the bind expression creates
a lambda functor for calling the name member
function of that class.
Nesting STL algorithm invocations
The BLL defines common STL algorithms as function object classes,
instances of which can be used as target functions in bind expressions.
For example, the following code iterates over the elements of a
two-dimensional array, and computes their sum.
int a[100][200];
int sum = 0;
std::for_each(a, a + 100,
bind(ll::for_each(), _1, _1 + 200, protect(sum += _1)));
The BLL versions of the STL algorithms are classes, which define the function call operator (or several overloaded ones) to call the corresponding function templates in the std namespace.
All these structs are placed in the subnamespace boost::lambda:ll.
Note that there is no easy way to express an overloaded member function
call in a lambda expression.
This limits the usefulness of nested STL algorithms, as for instance
the begin function has more than one overloaded
definitions in container templates.
In general, something analogous to the pseudo-code below cannot be written:
std::for_each(a.begin(), a.end(),
bind(ll::for_each(), _1.begin(), _1.end(), protect(sum += _1)));
Some aid for common special cases can be provided though.
The BLL defines two helper function object classes,
call_begin and call_end,
which wrap a call to the begin and, respectively,
end functions of a container, and return the
const_iterator type of the container.
With these helper templates, the above code becomes:
std::for_each(a.begin(), a.end(),
bind(ll::for_each(),
bind(call_begin(), _1), bind(call_end(), _1),
protect(sum += _1)));
Extending return type deduction system
In this section, we explain how to extend the return type deduction system
to cover user defined operators.
In many cases this is not necessary,
as the BLL defines default return types for operators.
For example, the default return type for all comparison operators is
bool, and as long as the user defined comparison operators
have a bool return type, there is no need to write new specializations
for the return type deduction classes.
Sometimes this cannot be avoided, though.
The overloadable user defined operators are either unary or binary.
For each arity, there are two traits templates that define the
return types of the different operators.
Hence, the return type system can be extended by providing more
specializations for these templates.
The templates for unary functors are
plain_return_type_1<Action, A>
and
return_type_1<Action, A>
, and
plain_return_type_2<Action, A, B>
and
return_type_2<Action, A, B>
respectively for binary functors.
The first parameter (Action) to all these templates
is the action class, which specifies the operator.
Operators with similar return type rules are grouped together into
action groups,
and only the action class and action group together define the operator
unambiguously.
As an example, the action type
arithmetic_action<plus_action> stands for
operator+.
The complete listing of different action types is shown in
.
The latter parameters, A in the unary case,
or A and B in the binary case,
stand for the argument types of the operator call.
The two sets of templates,
plain_return_type_n and
return_type_n
(n is 1 or 2) differ in the way how parameter types
are presented to them.
For the former templates, the parameter types are always provided as
non-reference types, and do not have const or volatile qualifiers.
This makes specializing easy, as commonly one specialization for each
user defined operator, or operator group, is enough.
On the other hand, if a particular operator is overloaded for different
cv-qualifications of the same argument types,
and the return types of these overloaded versions differ, a more fine-grained control is needed.
Hence, for the latter templates, the parameter types preserve the
cv-qualifiers, and are non-reference types as well.
The downside is, that for an overloaded set of operators of the
kind described above, one may end up needing up to
16 return_type_2 specializations.
Suppose the user has overloaded the following operators for some user defined
types X, Y and Z:
Z operator+(const X&, const Y&);
Z operator-(const X&, const Y&);
Now, one can add a specialization stating, that if the left hand argument
is of type X, and the right hand one of type
Y, the return type of all such binary arithmetic
operators is Z:
namespace boost {
namespace lambda {
template<class Act>
struct plain_return_type_2<arithmetic_action<Act>, X, Y> {
typedef Z type;
};
}
}
Having this specialization defined, BLL is capable of correctly
deducing the return type of the above two operators.
Note, that the specializations must be in the same namespace,
::boost::lambda, with the primary template.
For brevity, we do not show the namespace definitions in the examples below.
It is possible to specialize on the level of an individual operator as well,
in addition to providing a specialization for a group of operators.
Say, we add a new arithmetic operator for argument types X
and Y:
X operator*(const X&, const Y&);
Our first rule for all arithmetic operators specifies that the return
type of this operator is Z,
which obviously is not the case.
Hence, we provide a new rule for the multiplication operator:
template<>
struct plain_return_type_2<arithmetic_action<multiply_action>, X, Y> {
typedef X type;
};
The specializations can define arbitrary mappings from the argument types
to the return type.
Suppose we have some mathematical vector type, templated on the element type:
template <class T> class my_vector;
Suppose the addition operator is defined between any two
my_vector instantiations,
as long as the addition operator is defined between their element types.
Furthermore, the element type of the resulting my_vector
is the same as the result type of the addition between the element types.
E.g., adding my_vector<int> and
my_vector<double> results in
my_vector<double>.
The BLL has traits classes to perform the implicit built-in and standard
type conversions between integral, floating point, and complex classes.
Using BLL tools, the addition operator described above can be defined as:
template<class A, class B>
my_vector<typename return_type_2<arithmetic_action<plus_action>, A, B>::type>
operator+(const my_vector<A>& a, const my_vector<B>& b)
{
typedef typename
return_type_2<arithmetic_action<plus_action>, A, B>::type res_type;
return my_vector<res_type>();
}
To allow BLL to deduce the type of my_vector
additions correctly, we can define:
template<class A, class B>
class plain_return_type_2<arithmetic_action<plus_action>,
my_vector<A>, my_vector<B> > {
typedef typename
return_type_2<arithmetic_action<plus_action>, A, B>::type res_type;
public:
typedef my_vector<res_type> type;
};
Note, that we are reusing the existing specializations for the
BLL return_type_2 template,
which require that the argument types are references.
Practical considerationsPerformanceIn theory, all overhead of using STL algorithms and lambda functors
compared to hand written loops can be optimized away, just as the overhead
from standard STL function objects and binders can.
Depending on the compiler, this can also be true in practice.
We ran two tests with the GCC 3.0.4 compiler on 1.5 GHz Intel Pentium 4.
The optimization flag -03 was used.
In the first test we compared lambda functors against explicitly written
function objects.
We used both of these styles to define unary functions which multiply the
argument repeatedly by itself.
We started with the identity function, going up to
x5.
The expressions were called inside a std::transform loop,
reading the argument from one std::vector<int>
and placing the result into another.
The length of the vectors was 100 elements.
The running times are listed in
.
We can observe that there is no significant difference between the
two approaches.
In the second test we again used std::transform to
perform an operation to each element in a 100-element long vector.
This time the element type of the vectors was double
and we started with very simple arithmetic expressions and moved to
more complex ones.
The running times are listed in .
Here, we also included classic STL style unnamed functions into tests.
We do not show these expressions, as they get rather complex.
For example, the
last expression in written with
classic STL tools contains 7 calls to compose2,
8 calls to bind1st
and altogether 14 constructor invocations for creating
multiplies, minus
and plus objects.
In this test the BLL expressions are a little slower (roughly 10% on average,
less than 14% in all cases)
than the corresponding hand-written function objects.
The performance hit is a bit greater with classic STL expressions,
up to 27% for the simplest expressios.
The tests suggest that the BLL does not introduce a loss of performance
compared to STL function objects.
With a reasonable optimizing compiler, one should expect the performance characteristics be comparable to using classic STL.
Moreover, with simple expressions the performance can be expected to be close
to that of explicitly written function objects.
Note however, that evaluating a lambda functor consist of a sequence of calls to small functions that are declared inline.
If the compiler fails to actually expand these functions inline,
the performance can suffer.
The running time can more than double if this happens.
Although the above tests do not include such an expression, we have experienced
this for some seemingly simple expressions.
Test 1
CPU time of expressions with integer multiplication written as a lambda expression and as a traditional hand-coded function object class.
The running times are expressed in arbitrary units.
expressionlambda expressionhand-coded function objectx240230x*x340350x*x*x770760x*x*x*x11801210x*x*x*x*x19501910
Test 2
CPU time of arithmetic expressions written as lambda
expressions, as classic STL unnamed functions (using compose2, bind1st etc.) and as traditional hand-coded function object classes.
Using BLL terminology,
a and b are bound arguments in the expressions, and x is open.
All variables were of types double.
The running times are expressed in arbitrary units.
Some additional performance testing with an earlier version of the
library is described
.
About compilingThe BLL uses templates rather heavily, performing numerous recursive instantiations of the same templates.
This has (at least) three implications:
While it is possible to write incredibly complex lambda expressions, it probably isn't a good idea.
Compiling such expressions may end up requiring a lot of memory
at compile time, and being slow to compile.
The types of lambda functors that result from even the simplest lambda expressions are cryptic.
Usually the programmer doesn't need to deal with the lambda functor types at all, but in the case of an error in a lambda expression, the compiler usually outputs the types of the lambda functors involved.
This can make the error messages very long and difficult to interpret, particularly if the compiler outputs the whole chain of template instantiations.
The C++ Standard suggests a template nesting level of 17 to help detect infinite recursion.
Complex lambda templates can easily exceed this limit.
Most compilers allow a greater number of nested templates, but commonly require the limit explicitly increased with a command line argument.
Portability
The BLL works with the following compilers, that is, the compilers are capable of compiling the test cases that are included with the BLL:
GCC 3.0.4
KCC 4.0f with EDG 2.43.1
GCC 2.96 (fails with one test case, the exception_test.cpp results in an internal compiler error.
)
Test coverageThe following list describes the test files included and the features that each file covers:
bind_tests_simple.cpp : Bind expressions of different arities and types of target functions: function pointers, function objects and member functions.
Function composition with bind expressions.bind_tests_simple_function_references.cpp :
Repeats all tests from bind_tests_simple.cpp where the target function is a function pointer, but uses function references instead.
bind_tests_advanced.cpp : Contains tests for nested bind expressions, unlambda, protect, const_parameters and break_const.
Tests passing lambda functors as actual arguments to other lambda functors, currying, and using the sig template to specify the return type of a function object.
operator_tests_simple.cpp :
Tests using all operators that are overloaded for lambda expressions, that is, unary and binary arithmetic,
bitwise,
comparison,
logical,
increment and decrement,
compound,
assignment,
subscrict,
address of,
dereference, and comma operators.
The streaming nature of shift operators is tested, as well as pointer arithmetic with plus and minus operators.
member_pointer_test.cpp : The pointer to member operator is complex enough to warrant a separate test file.
control_structures.cpp :
Tests for the looping and if constructs.
switch_construct.cpp :
Includes tests for all supported arities of the switch statement, both with and without the default case.
exception_test.cpp :
Includes tests for throwing exceptions and for try/catch constructs with varying number of catch blocks.
constructor_tests.cpp :
Contains tests for constructor, destructor, new_ptr, delete_ptr, new_array and delete_array.
cast_test.cpp : Tests for the four cast expressions, as well as typeid and sizeof.
extending_return_type_traits.cpp : Tests extending the return type deduction system for user defined types.
Contains several user defined operators and the corresponding specializations for the return type deduction templates.
is_instance_of_test.cpp : Includes tests for an internally used traits template, which can detect whether a given type is an instance of a certain template or not.
bll_and_function.cpp :
Contains tests for using boost::function together with lambda functors.
Relation to other Boost librariesBoost FunctionSometimes it is convenient to store lambda functors in variables.
However, the types of even the simplest lambda functors are long and unwieldy, and it is in general unfeasible to declare variables with lambda functor types.
The Boost Function library defines wrappers for arbitrary function objects, for example
lambda functors; and these wrappers have types that are easy to type out.
For example:
boost::function<int(int, int)> f = _1 + _2;
boost::function<int&(int&)> g = (_1 += 10);
int i = 1, j = 2;
f(i, j); // returns 3
g(i); // sets i to = 11;
The return and parameter types of the wrapped function object must be written explicilty as the template argument to the wrapper template boost::function; even when lambda functors, which otherwise have generic parameters, are wrapped.
Wrapping a function object with boost::function introduces a performance cost comparable to virtual function dispatch, though virtual functions are not actually used.
Note that storing lambda functors inside boost::function
introduces a danger.
Certain types of lambda functors may store references to the bound
arguments, instead as taking copies of the arguments of the lambda expression.
When temporary lambda functor objects are used
in STL algorithm invocations this is always safe, as the lambda functor gets
destructed immediately after the STL algortihm invocation is completed.
However, a lambda functor wrapped inside boost::function
may continue to exist longer, creating the possibility of dangling references.
For example:
int* sum = new int();
*sum = 0;
boost::function<int&(int)> counter = *sum += _1;
counter(5); // ok, *sum = 5;
delete sum;
counter(3); // error, *sum does not exist anymore
Boost BindThe Boost Bind library has partially overlapping functionality with the BLL.
Basically, the Boost Bind library (BB in the sequel) implements the bind expression part of BLL.
There are, however, some semantical differerences.
The BLL and BB evolved separately, and have different implementations.
This means that the bind expressions from the BB cannot be used within
bind expressions, or within other type of lambda expressions, of the BLL.
The same holds for using BLL bind expressions in the BB.
The libraries can coexist, however, as
the names of the BB library are in boost namespace,
whereas the BLL names are in boost::lambda namespace.
The BLL requires a compiler that is reasonably conformant to the
C++ standard, whereas the BB library is more portable, and works with
a larger set of compilers.
The following two sections describe what are the semantic differences
between the bind expressions in BB and BLL.
First argument of bind expression
In BB the first argument of the bind expression, the target function,
is treated differently from the other arguments,
as no argument substitution takes place within that argument.
In BLL the first argument is not a special case in this respect.
For example:
template<class F>
int foo(const F& f) {
int x;
..
bind(f, _1)(x);
...
}
int bar(int, int);
nested(bind(bar, 1, _1));
The bind expression inside foo becomes:
bind(bind(bar, 1, _1), _1)(x)
The BLL interpretes this as:
bar(1, x)(x)
whereas the BB library as
bar(1, x)
To get this functionality in BLL, the bind expression inside the foo function can be written as:
bind(unlambda(f), _1)(x);
as explained in .
The BB library supports up to nine placeholders, while the BLL
defines only three placeholders.
The rationale for not providing more, is that the highest arity of the
function objects accepted by any STL algorithm is two.
The placeholder count is easy to increase in the BB library.
In BLL it is possible, but more laborous.
The BLL currently passes the actual arguments to the lambda functors
internally just as they are and does not wrap them inside a tuple object.
The reason for this is that some widely used compilers are not capable
of optimizing the intermediate tuple objects away.
The creation of the intermediate tuples would cause a significant
performance hit, particularly for the simplest (and thus the most common)
lambda functors.
We are working on a hybrid approach, which will allow more placeholders
but not compromise the performance of simple lambda functors.
Contributors
The main body of the library was written by Jaakko Järvi and Gary Powell.
We've got outside help, suggestions and ideas from Jeremy Siek, Peter Higley, Peter Dimov, Valentin Bonnard, William Kempf.
We would particularly like to mention Joel de Guzmann and his work with
Phoenix which has influenced BLL significantly, making it considerably simpler
to extend the library with new features.
Rationale for some of the design decisions
Lambda functor arity
The highest placeholder index in a lambda expression determines the arity of the resulting function object.
However, this is just the minimal arity, as the function object can take arbitrarily many arguments; those not needed are discarded.
Consider the two bind expressions and their invocations below:
bind(g, _3, _3, _3)(x, y, z);
bind(g, _1, _1, _1)(x, y, z);
This first line discards arguments x and
y, and makes the call:
g(z, z, z)
whereas the second line discards arguments y and
z, and calls:
g(x, x, x)
In earlier versions of the library, the latter line resulted in a compile
time error.
This is basically a tradeoff between safety and flexibility, and the issue
was extensively discussed during the Boost review period of the library.
The main points for the strict arity checking
was that it might
catch a programming error at an earlier time and that a lambda expression that
explicitly discards its arguments is easy to write:
(_3, bind(g, _1, _1, _1))(x, y, z);
This lambda expression takes three arguments.
The left-hand argument of the comma operator does nothing, and as comma
returns the result of evaluating the right-hand argument we end up with
the call
g(x, x, x)
even with the strict arity.
The main points against the strict arity checking were that the need to
discard arguments is commonplace, and should therefore be straightforward,
and that strict arity checking does not really buy that much more safety,
particularly as it is not symmetric.
For example, if the programmer wanted to write the expression
_1 + _2 but mistakenly wrote _1 + 2,
with strict arity checking, the complier would spot the error.
However, if the erroneous expression was 1 + _2 instead,
the error would go unnoticed.
Furthermore, weak arity checking simplifies the implementation a bit.
Following the recommendation of the Boost review, strict arity checking
was dropped.
STL94StepanovA. A.LeeM.The Standard Template LibraryHewlett-Packard Laboratories1994www.hpl.hp.com/techreportsSGI02The SGI Standard Template Library2002www.sgi.com/tech/stl/C++98International Standard, Programming Languages – C++ISO/IEC:148821998Jär99JärviJaakkoC++ Function Object Binders Made EasyLecture Notes in Computer Science1977Springer2000Jär00JärviJaakkoGaryPowellThe Lambda Library : Lambda Abstraction in C++Turku Centre for Computer ScienceTechnical Report 3782000www.tucs.fi/publicationsJär01JärviJaakkoGaryPowellThe Lambda Library : Lambda Abstraction in C++Second Workshop on C++ Template ProgrammingTampa Bay, OOPSLA'012001www.oonumerics.org/tmpw01/Jär03JärviJaakkoGaryPowellAndrewLumsdaineThe Lambda Library : unnamed functions in C++Software - Practice and Expreience33:259-2912003tupleThe Boost Tuple Librarywww.boost.org/libs/tuple/doc/tuple_users_guide.html2002type_traitsThe Boost type_traitswww.boost.org/libs/type_traits/2002refBoost refwww.boost.org/libs/bind/ref.html2002bindBoost Bind Librarywww.boost.org/libs/bind/bind.html2002functionBoost Function Librarywww.boost.org/libs/function/2002fc++The FC++ library: Functional Programming in C++SmaragdakisYannisBrianMcNamarawww.cc.gatech.edu/~yannis/fc++/2002VladimirPrus200220032004Vladimir PrusDistributed 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)
Boost.Program_optionsIntroductionThe program_options library allows program developers to obtain
program options, that is (name, value) pairs from the user,
via conventional methods such as command line and config file.Why would you use such a library, and why is it better than parsing
your command line by straightforward hand-written code?
It's easier. The syntax for declaring options is simple, and
the library itself is small. Things like conversion of option values to
desired type and storing into program variables are handled
automatically.
Error reporting is better. All the problems with the command line are
reported, while hand-written code can just misparse the input. In
addition, the usage message can be automatically generated, to
avoid falling out of sync with the real list of options.Options can be read from anywhere. Sooner or later the command
line will be not enough for your users, and you'll want config files
or maybe even environment variables. These can be added without significant
effort on your part.
Now let's see some examples of the library usage in the .
TutorialIn this section, we'll take a look at the most common usage scenarios
of the program_options library, starting with the simplest one. The examples
show only the interesting code parts, but the complete programs can be found
in the "BOOST_ROOT/libs/program_options/example" directory. Through all the
examples, we'll assume that the following namespace alias is in effect:
namespace po = boost::program_options;Getting StartedThe first example is the simplest possible: it only handles two
options. Here's the source code (the full program is in
"example/first.cpp"):
// Declare the supported options.
po::options_description desc("Allowed options");
desc.add_options()
("help", "produce help message")
("compression", po::value<int>(), "set compression level")
;
po::variables_map vm;
po::store(po::parse_command_line(ac, av, desc), vm);
po::notify(vm);
if (vm.count("help")) {
cout << desc << "\n";
return 1;
}
if (vm.count("compression")) {
cout << "Compression level was set to "
<< vm["compression"].as<int>() << ".\n";
} else {
cout << "Compression level was not set.\n";
}
We start by declaring all allowed options using the
options_description class. The add_options method of that
class returns a special proxy object that defines
operator(). Calls to that operator actually declare
options. The parameters are option name, information about value, and option
description. In this example, the first option has no value, and the second
one has a value of type int.
After that, an object of class variables_map is
declared. That class is intended to store values of options, and can store
values of arbitrary types. Next, the calls to store,
parse_command_line and notify functions cause
vm to contain all the options found on the command
line.And now, finally, we can use the options as we like. The
variables_map class can be used just like
std::map, except that values stored there must be retrieved
with the as method shown above. (If the type specified in the
call to the as method is different from the actually stored
type, an exception is thrown.)
It's now a good time to try compiling the code yourself, but if
you're not yet ready, here's an example session:
$bin/gcc/debug/first
Compression level was not set.
$bin/gcc/debug/first --help
Allowed options:
--help : produce help message
--compression arg : set compression level
$bin/gcc/debug/first --compression 10
Compression level was set to 10.
Option DetailsAn option value, surely, can have other types than int, and
can have other interesting properties, which we'll discuss right now. The
complete version of the code snipped below can be found in
"example/options_description.cpp".Imagine we're writing a compiler. It should take the optimization
level, a number of include paths, and a number of input files, and perform some
interesting work. Let's describe the options:
int opt;
po::options_description desc("Allowed options");
desc.add_options()
("help", "produce help message")
("optimization", po::value<int>(&opt)->default_value(10),
"optimization level")
("include-path,I", po::value< vector<string> >(),
"include path")
("input-file", po::value< vector<string> >(), "input file")
;
The "--help" option should be familiar from the previous example.
It's a good idea to have this option in all cases.The "optimization" option shows two new features. First, we specify
the address of the variable(&opt). After storing values, that
variable will have the value of the option. Second, we specify a default
value of 10, which will be used if no value is specified by the user.
The "include-path" option is an example of the only case where
the interface of the options_description class serves only one
source -- the command line. Users typically like to use short option names
for common options, and the "include-path,I" name specifies that short
option name is "I". So, both "--include-path" and "-I" can be used.
The "input-file" option specifies the list of files to
process. That's okay for a start, but, of course, writing something like:
compiler --input-file=a.cpp
is a little non-standard, compared with
compiler a.cpp
We'll address this in a moment.
The command line tokens which have no option name, as above, are
called "positional options" by this library. They can be handled
too. With a little help from the user, the library can decide that "a.cpp"
really means the same as "--input-file=a.cpp". Here's the additional code
we need:
po::positional_options_description p;
p.add("input-file", -1);
po::variables_map vm;
po::store(po::command_line_parser(ac, av).
options(desc).positional(p).run(), vm);
po::notify(vm);
The first two lines say that all positional options should be translated
into "input-file" options. Also note that we use the
command_line_parser class to parse the command
line, not the parse_command_line
function. The latter is a convenient wrapper for simple cases, but now we
need to pass additional information.
By now, all options are described and parsed. We'll save ourselves the
trouble of implementing the rest of the compiler logic and only print the
options:
if (vm.count("include-path"))
{
cout << "Include paths are: "
<< vm["include-path"].as< vector<string> >() << "\n";
}
if (vm.count("input-file"))
{
cout << "Input files are: "
<< vm["input-file"].as< vector<string> >() << "\n";
}
cout << "Optimization level is " << opt << "\n";
Here's an example session:
$bin/gcc/debug/options_description --help
Usage: options_description [options]
Allowed options:
--help : produce help message
--optimization arg : optimization level
-I [ --include-path ] arg : include path
--input-file arg : input file
$bin/gcc/debug/options_description
Optimization level is 10
$bin/gcc/debug/options_description --optimization 4 -I foo a.cpp
Include paths are: foo
Input files are: a.cpp
Optimization level is 4
Oops, there's a slight problem. It's still possible to specify the
"--input-file" option, and usage message says so, which can be confusing
for the user. It would be nice to hide this information, but let's wait
for the next example.
Multiple SourcesIt's quite likely that specifying all options to our compiler on the
command line will annoy users. What if a user installs a new library and
wants to always pass an additional command line element? What if he has
made some choices which should be applied on every run? It's desirable to
create a config file with common settings which will be used together with
the command line.
Of course, there will be a need to combine the values from command
line and config file. For example, the optimization level specified on the
command line should override the value from the config file. On the other
hand, include paths should be combined.
Let's see the code now. The complete program is in
"examples/multiple_sources.cpp". The option definition has two interesting
details. First, we declare several instances of the
options_description class. The reason is that, in general,
not all options are alike. Some options, like "input-file" above, should
not be presented in an automatic help message. Some options make sense only
in the config file. Finally, it's nice to have some structure in the help message,
not just a long list of options. Let's declare several option groups:
// Declare a group of options that will be
// allowed only on command line
po::options_description generic("Generic options");
generic.add_options()
("version,v", "print version string")
("help", "produce help message")
;
// Declare a group of options that will be
// allowed both on command line and in
// config file
po::options_description config("Configuration");
config.add_options()
("optimization", po::value<int>(&opt)->default_value(10),
"optimization level")
("include-path,I",
po::value< vector<string> >()->composing(),
"include path")
;
// Hidden options, will be allowed both on command line and
// in config file, but will not be shown to the user.
po::options_description hidden("Hidden options");
hidden.add_options()
("input-file", po::value< vector<string> >(), "input file")
;
Note the call to the composing method in the declaration of the
"include-path" option. It tells the library that values from different sources
should be composed together, as we'll see shortly.
The add method of the options_description
class can be used to further group the options:
po::options_description cmdline_options;
cmdline_options.add(generic).add(config).add(hidden);
po::options_description config_file_options;
config_file_options.add(config).add(hidden);
po::options_description visible("Allowed options");
visible.add(generic).add(config);
The parsing and storing of values follows the usual pattern, except that
we additionally call parse_config_file, and
call the store function twice. But what
happens if the same value is specified both on the command line and in
config file? Usually, the value stored first is preferred. This is what
happens for the "--optimization" option. For "composing" options, like
"include-file", the values are merged.
Here's an example session:
$bin/gcc/debug/multiple_sources
Include paths are: /opt
Optimization level is 1
$bin/gcc/debug/multiple_sources --help
Allows options:
Generic options:
-v [ --version ] : print version string
--help : produce help message
Configuration:
--optimization n : optimization level
-I [ --include-path ] path : include path
$bin/gcc/debug/multiple_sources --optimization=4 -I foo a.cpp b.cpp
Include paths are: foo /opt
Input files are: a.cpp b.cpp
Optimization level is 4
The first invocation uses values from the configuration file. The second
invocation also uses values from command line. As we see, the include
paths on the command line and in the configuration file are merged,
while optimization is taken from the command line.
Library OverviewIn the tutorial section, we saw several examples of library usage.
Here we will describe the overall library design including the primary
components and their function.
The library has three main components:
The options description component, which describes the allowed options
and what to do with the values of the options.
The parsers component, which uses this information to find option names
and values in the input sources and return them.
The storage component, which provides the
interface to access the value of an option. It also converts the string
representation of values that parsers return into desired C++ types.
To be a little more concrete, the options_description
class is from the options description component, the
parse_command_line function is from the parsers component, and the
variables_map class is from the storage component. In the tutorial we've learned how those components can be used by the
main function to parse the command line and config
file. Before going into the details of each component, a few notes about
the world outside of main.
For that outside world, the storage component is the most important. It
provides a class which stores all option values and that class can be
freely passed around your program to modules which need access to the
options. All the other components can be used only in the place where
the actual parsing is the done. However, it might also make sense for the
individual program modules to describe their options and pass them to the
main module, which will merge all options. Of course, this is only
important when the number of options is large and declaring them in one
place becomes troublesome.
Options Description ComponentThe options description component has three main classes:
option_description, value_semantic and options_description. The
first two together describe a single option. The option_description
class contains the option's name, description and a pointer to value_semantic,
which, in turn, knows the type of the option's value and can parse the value,
apply the default value, and so on. The options_description class is a
container for instances of option_description.
For almost every library, those classes could be created in a
conventional way: that is, you'd create new options using constructors and
then call the add method of options_description. However,
that's overly verbose for declaring 20 or 30 options. This concern led
to creation of the syntax that you've already seen:
options_description desc;
desc.add_options()
("help", "produce help")
("optimization", value<int>()->default_value(10), "optimization level")
;
The call to the value function creates an instance of
a class derived from the value_semantic class: typed_value.
That class contains the code to parse
values of a specific type, and contains a number of methods which can be
called by the user to specify additional information. (This
essentially emulates named parameters of the constructor.) Calls to
operator() on the object returned by add_options
forward arguments to the constructor of the option_description
class and add the new instance.
Note that in addition to the
value, library provides the bool_switch
function, and user can write his own function which will return
other subclasses of value_semantic with
different behaviour. For the remainder of this section, we'll talk only
about the value function.
The information about an option is divided into syntactic and
semantic. Syntactic information includes the name of the option and the
number of tokens which can be used to specify the value. This
information is used by parsers to group tokens into (name, value) pairs,
where value is just a vector of strings
(std::vector<std::string>). The semantic layer
is responsible for converting the value of the option into more usable C++
types.
This separation is an important part of library design. The parsers
use only the syntactic layer, which takes away some of the freedom to
use overly complex structures. For example, it's not easy to parse
syntax like: calc --expression=1 + 2/3 because it's not
possible to parse 1 + 2/3 without knowing that it's a C
expression. With a little help from the user the task becomes trivial,
and the syntax clear: calc --expression="1 + 2/3"Syntactic informationThe syntactic information is provided by the
boost::program_options::options_description class
and some methods of the
boost::program_options::value_semantic class.
The simplest usage is illustrated below:
options_description desc;
desc.add_options()
("help", "produce help message")
;
This declares one option named "help" and associates a description with
it. The user is not allowed to specify any value.
To make an option accept a value, you'd need the
value function mentioned above:
options_description desc;
desc.add_options()
("compression", "compression level", value<string>())
("verbose", "verbosity level", value<string>()->implicit())
("email", "email to send to", value<string>()->multitoken());
With these declarations, the user must specify a value for
the first option, using a single token. For the second option, the user
may either provide a single token for the value, or no token at
all. For the last option, the value can span several tokens. For
example, the following command line is OK:
test --compression 10 --verbose --email beadle@mars beadle2@mars
Semantic informationThe semantic information is completely provided by the
boost::program_options::value_semantic class. For
example:
options_description desc;
desc.add_options()
("compression", "compression level", value<int>()->default(10));
("email", "email", value< vector<string> >()
->composing()->notify(&your_function);
These declarations specify that default value of the first option is 10,
that the second option can appear several times and all instances should
be merged, and that after parsing is done, the library will call
function &your_function, passing the value of the
"email" option as argument.
Positional optionsOur definition of option as (name, value) pairs is simple and
useful, but in one special case of the command line, there's a
problem. A command line can include a positional option,
which does not specify any name at all, for example:
archiver --compression=9 /etc/passwd
Here, the "/etc/passwd" element does not have any option name.
One solution is to ask the user to extract positional options
himself and process them as he likes. However, there's a nicer approach
-- provide a method to automatically assign the names for positional
options, so that the above command line can be interpreted the same way
as:
archiver --compression=9 --input-file=/etc/passwd
The positional_options_description class allows the command line
parser to assign the names. The class specifies how many positional options
are allowed, and for each allowed option, specifies the name. For example:
positional_options_description pd; pd.add("input-file", 1, 1);
specifies that for exactly one, first, positional
option the name will be "input-file".
It's possible to specify that a number, or even all positional options, be
given the same name.
positional_options_description pd;
pd.add("output-file", 2, 2).add_optional("input-file", 0, -1);
In the above example, the first two positional options will be associated
with name "output-file", and any others with the name "input-file".
Parsers ComponentThe parsers component splits input sources into (name, value) pairs.
Each parser looks for possible options and consults the options
description component to determine if the option is known and how its value
is specified. In the simplest case, the name is explicitly specified,
which allows the library to decide if such option is known. If it is known, the
value_semantic instance determines how the value is specified. (If
it is not known, an exception is thrown.) Common
cases are when the value is explicitly specified by the user, and when
the value cannot be specified by the user, but the presence of the
option implies some value (for example, true). So, the
parser checks that the value is specified when needed and not specified
when not needed, and returns new (name, value) pair.
To invoke a parser you typically call a function, passing the options
description and command line or config file or something else.
The results of parsing are returned as an instance of the parsed_options
class. Typically, that object is passed directly to the storage
component. However, it also can be used directly, or undergo some additional
processing.
There are three exceptions to the above model -- all related to
traditional usage of the command line. While they require some support
from the options description component, the additional complexity is
tolerable.
The name specified on the command line may be
different from the option name -- it's common to provide a "short option
name" alias to a longer name. It's also common to allow an abbreviated name
to be specified on the command line.
Sometimes it's desirable to specify value as several
tokens. For example, an option "--email-recipient" may be followed
by several emails, each as a separate command line token. This
behaviour is supported, though it can lead to parsing ambiguities
and is not enabled by default.
The command line may contain positional options -- elements
which don't have any name. The command line parser provides a
mechanism to guess names for such options, as we've seen in the
tutorial.
Storage ComponentThe storage component is responsible for:
Storing the final values of an option into a special class and in
regular variablesHandling priorities among different sources.Calling user-specified notify functions with the final
values of options.Let's consider an example:
variables_map vm;
store(parse_command_line(argc, argv, desc), vm);
store(parse_config_file("example.cfg", desc), vm);
notify(vm);
The variables_map class is used to store the option
values. The two calls to the store function add values
found on the command line and in the config file. Finally the call to
the notify function runs the user-specified notify
functions and stores the values into regular variables, if needed.
The priority is handled in a simple way: the store
function will not change the value of an option if it's already
assigned. In this case, if the command line specifies the value for an
option, any value in the config file is ignored.
Don't forget to call the notify function after you've
stored all parsed values.Annotated List of SymbolsThe following table describes all the important symbols in the
library, for quick access.SymbolDescriptionOptions description componentoptions_descriptiondescribes a number of optionsvaluedefines the option's valueParsers componentparse_command_lineparses command lineparse_config_fileparses config fileparse_environmentparses environmentStorage componentvariables_mapstorage for option valuesHow ToThis section describes how the library can be used in specific
situations.Non-conventional SyntaxSometimes, standard command line syntaxes are not enough. For
example, the gcc compiler has "-frtti" and -fno-rtti" options, and this
syntax is not directly supported.
additional parserFor such cases, the library allows the user to provide an
additional parser -- a function which will be called on each
command line element, before any processing by the library. If the
additional parser recognises the syntax, it returns the option name and
value, which are used directly. The above example can be handled by the
following code:
pair<string, string> reg_foo(const string& s)
{
if (s.find("-f") == 0) {
if (s.substr(2, 3) == "no-")
return make_pair(s.substr(5), string("false"));
else
return make_pair(s.substr(2), string("true"));
} else {
return make_pair(string(), string());
}
}
Here's the definition of the additional parser. When parsing the command
line, we pass the additional parser:
store(command_line_parser(ac, av).options(desc).extra_parser(reg_foo)
.run(), vm);
The complete example can be found in the "example/custom_syntax.cpp"
file.
Response Filesresponse filesSome operating system have very low limits of the command line
length. The common way to work around those limitations is using
response files. A response file is just a
configuration file which uses the same syntax as the command line. If
the command line specifies a name of response file to use, it's loaded
and parsed in addition to the command line. The library does not
provide direct support for response files, so you'll need to write some
extra code.
First, you need to define an option for the response file:
("response-file", value<string>(),
"can be specified with '@name', too")
Second, you'll need an additional parser to support the standard syntax
for specifying response files: "@file":
pair<string, string> at_option_parser(string const&s)
{
if ('@' == s[0])
return std::make_pair(string("response-file"), s.substr(1));
else
return pair<string, string>();
}
Finally, when the "response-file" option is found, you'll have to
load that file and pass it to the command line parser. This part is the
hardest. We'll use the Boost.Tokenizer library, which works but has some
limitations. You might also consider Boost.StringAlgo. The code is:
if (vm.count("response-file")) {
// Load the file and tokenize it
ifstream ifs(vm["response-file"].as<string>().c_str());
if (!ifs) {
cout << "Could no open the response file\n";
return 1;
}
// Read the whole file into a string
stringstream ss;
ss << ifs.rdbuf();
// Split the file content
char_separator<char> sep(" \n\r");
tokenizer<char_separator<char> > tok(ss.str(), sep);
vector<string> args;
copy(tok.begin(), tok.end(), back_inserter(args));
// Parse the file and store the options
store(command_line_parser(args).options(desc).run(), vm);
}
The complete example can be found in the "example/response_file.cpp"
file.
Winmain Command LineOn the Windows operating system, GUI applications receive the
command line as a single string, not split into elements. For that reason,
the command line parser cannot be used directly. At least on some
compilers, it is possible to obtain
the split command line, but it's not clear if all compilers support the
same mechanism on all versions of the operating system. The
split_command_line function is a portable mechanism provided
by the library.Here's an example of use:
vector<string> args = split_winmain(lpCmdLine);
store(command_line_parser(args).options(desc).run(), vm);
The function is an overload for wchar_t strings, so can
also be used in Unicode applications.
Option Groups and Hidden OptionsHaving a single instance of the options_description class with all
the program's options can be problematic:
Some options make sense only for specific source, for example,
configuration files.The user would prefer some structure in the generated help message.Some options shouldn't appear in the generated help message at all.To solve the above issues, the library allows a programmer to create several
instances of the options_description class, which can be merged in
different combinations. The following example will define three groups of
options: command line specific, and two options group for specific program
modules, only one of which is shown in the generated help message.
Each group is defined using standard syntax. However, you should
use reasonable names for each options_description instance:
options_description general("General options");
general.add_options()
("help", "produce a help message")
("help-module", value<string>()->implicit(),
"produce a help for a given module")
("version", "output the version number")
;
options_description gui("GUI options");
gui.add_options()
("display", value<string>(), "display to use")
;
options_description backend("Backend options");
backend.add_options()
("num-threads", value<int>(), "the initial number of threads")
;
After declaring options groups, we merge them in two
combinations. The first will include all options and be used for parsing. The
second will be used for the "--help" option.
// Declare an options description instance which will include
// all the options
options_description all("Allowed options");
all.add(general).add(gui).add(backend);
// Declare an options description instance which will be shown
// to the user
options_description visible("Allowed options");
visible.add(general).add(gui);
What is left is to parse and handle the options:
variables_map vm;
store(parse_command_line(ac, av, all), vm);
if (vm.count("help"))
{
cout << visible;
return 0;
}
if (vm.count("help-module")) {
const string& s = vm["help-module"].as<string>();
if (s == "gui") {
cout << gui;
} else if (s == "backend") {
cout << backend;
} else {
cout << "Unknown module '"
<< s << "' in the --help-module option\n";
return 1;
}
return 0;
}
if (vm.count("num-threads")) {
cout << "The 'num-threads' options was set to "
<< vm["num-threads"].as<int>() << "\n";
}
When parsing the command line, all options are allowed. The "--help"
message, however, does not include the "Backend options" group -- the
options in that group are hidden. The user can explicitly force the
display of that options group by passing "--help-module backend"
option. The complete example can be found in the
"example/option_groups.cpp" file.
Custom ValidatorsBy default, the conversion of option's value from string into C++
type is done using iostreams, which sometimes is not convenient. The
library allows the user to customize the conversion for specific
classes. In order to do so, the user should provide suitable overload of
the validate function.
Let's first define a simple class:
struct magic_number {
public:
magic_number(int n) : n(n) {}
int n;
};
and then overload the validate function:
void validate(boost::any& v,
const std::vector<std::string>& values,
magic_number* target_type, int)
{
static regex r("\\d\\d\\d-(\\d\\d\\d)");
using namespace boost::program_options;
// Make sure no previous assignment to 'a' was made.
validators::check_first_occurence(v);
// Extract the first string from 'values'. If there is more than
// one string, it's an error, and exception will be thrown.
const string& s = validators::get_single_string(values);
// Do regex match and convert the interesting part to
// int.
smatch match;
if (regex_match(s, match, r)) {
v = any(magic_number(lexical_cast<int>(match[1])));
} else {
throw validation_error("invalid value");
}
}
The function takes four parameters. The first is the storage
for the value, and in this case is either empty or contains an instance of
the magic_number class. The second is the list of strings
found in the next occurrence of the option. The remaining two parameters
are needed to workaround the lack of partial template specialization and
partial function template ordering on some compilers.
The function first checks that we don't try to assign to the same
option twice. Then it checks that only a single string was passed
in. Next the string is verified with the help of the Boost.Regex
library. If that test is passed, the parsed value is stored into the
v variable.
The complete example can be found in the "example/regex.cpp" file.
Unicode SupportTo use the library with Unicode, you'd need to:
Use Unicode-aware parsers for Unicode inputRequire Unicode support for options which need itMost of the parsers have Unicode versions. For example, the
parse_command_line function has an overload which takes
wchar_t strings, instead of ordinary char.
Even if some of the parsers are Unicode-aware, it does not mean you
need to change definition of all the options. In fact, for many options,
like integer ones, it makes no sense. To make use of Unicode you'll need
some Unicode-aware options. They are different from
ordinary options in that they accept wstring input, and
process it using wide character streams. Creating an Unicode-aware option
is easy: just use the the wvalue function instead of the
regular value.
When an ascii parser passes data to an ascii option, or a Unicode
parser passes data to a Unicode option, the data are not changed at
all. So, the ascii option will see a string in local 8-bit encoding, and
the Unicode option will see whatever string was passed as the Unicode
input.
What happens when Unicode data is passed to an ascii option, and
vice versa? The library automatically performs the conversion from
Unicode to local 8-bit encoding. For example, if command line is in
ascii, but you use wstring options, then the ascii input
will be converted into Unicode.
To perform the conversion, the library uses the codecvt<wchar_t,
char> locale facet from the global locale. If
you want to work with strings that use local 8-bit encoding (as opposed to
7-bit ascii subset), your application should start with:
locale::global(locale(""));
which would set up the conversion facet according to the user's selected
locale.
It's wise to check the status of the C++ locale support on your
implementation, though. The quick test involves three steps:
Go the the "test" directory and build the "test_convert" binary.Set some non-ascii locale in the environmemt. On Linux, one can
run, for example:
$ export LC_CTYPE=ru_RU.KOI8-R
Run the "test_convert" binary with any non-ascii string in the
selected encoding as its parameter. If you see a list of Unicode codepoints,
everything's OK. Otherwise, locale support on your system might be
broken.Design DiscussionThis section focuses on some of the design questions.
Unicode SupportUnicode support was one of the features specifically requested
during the formal review. Throughout this document "Unicode support" is
a synonym for "wchar_t" support, assuming that "wchar_t" always uses
Unicode encoding. Also, when talking about "ascii" (in lowercase) we'll
not mean strict 7-bit ASCII encoding, but rather "char" strings in local
8-bit encoding.
Generally, "Unicode support" can mean
many things, but for the program_options library it means that:
Each parser should accept either char*
or wchar_t*, correctly split the input into option
names and option values and return the data.
For each option, it should be possible to specify whether the conversion
from string to value uses ascii or Unicode.
The library guarantees that:
ascii input is passed to an ascii value without change
Unicode input is passed to a Unicode value without changeascii input passed to a Unicode value, and Unicode input
passed to an ascii value will be converted using a codecvt
facet (which may be specified by the user(which can be
specified by the user)
The important point is that it's possible to have some "ascii
options" together with "Unicode options". There are two reasons for
this. First, for a given type you might not have the code to extract the
value from Unicode string and it's not good to require that such code be written.
Second, imagine a reusable library which has some options and exposes
options description in its interface. If all
options are either ascii or Unicode, and the library does not use any
Unicode strings, then the author will likely to use ascii options, which
would make the library unusable inside Unicode
applications. Essentially, it would be necessary to provide two versions
of the library -- ascii and Unicode.
Another important point is that ascii strings are passed though
without modification. In other words, it's not possible to just convert
ascii to Unicode and process the Unicode further. The problem is that the
default conversion mechanism -- the codecvt facet -- might
not work with 8-bit input without additional setup.
The Unicode support outlined above is not complete. For example, we
don't plan allow Unicode in option names. Unicode support is hard and
requires a Boost-wide solution. Even comparing two arbitrary Unicode
strings is non-trivial. Finally, using Unicode in option names is
related to internationalization, which has it's own
complexities. E.g. if option names depend on current locale, then all
program parts and other parts which use the name must be
internationalized too.
The primary question in implementing the Unicode support is whether
to use templates and std::basic_string or to use some
internal encoding and convert between internal and external encodings on
the interface boundaries.
The choice, mostly, is between code size and execution
speed. A templated solution would either link library code into every
application that uses the library (thereby making shared library
impossible), or provide explicit instantiations in the shared library
(increasing its size). The solution based on internal encoding would
necessarily make conversions in a number of places and will be somewhat slower.
Since speed is generally not an issue for this library, the second
solution looks more attractive, but we'll take a closer look at
individual components.
For the parsers component, we have three choices:
Use a fully templated implementation: given a string of a
certain type, a parser will return a parsed_options instance
with strings of the same type (i.e. the parsed_options class
will be templated).Use internal encoding: same as above, but strings will be converted to and
from the internal encoding.Use and partly expose the internal encoding: same as above,
but the strings in the parsed_options instance will be in the
internal encoding. This might avoid a conversion if
parsed_options instance is passed directly to other components,
but can be also dangerous or confusing for a user.
The second solution appears to be the best -- it does not increase
the code size much and is cleaner than the third. To avoid extra
conversions, the Unicode version of parsed_options can also store
strings in internal encoding.
For the options descriptions component, we don't have much
choice. Since it's not desirable to have either all options use ascii or all
of them use Unicode, but rather have some ascii and some Unicode options, the
interface of the value_semantic must work with both. The only way is
to pass an additional flag telling if strings use ascii or internal encoding.
The instance of value_semantic can then convert into some
other encoding if needed.
For the storage component, the only affected function is store.
For Unicode input, the store function should convert the value to the
internal encoding. It should also inform the value_semantic class
about the used encoding.
Finally, what internal encoding should we use? The
alternatives are:
std::wstring (using UCS-4 encoding) and
std::string (using UTF-8 encoding). The difference between
alternatives is:
Speed: UTF-8 is a bit slowerSpace: UTF-8 takes less space when input is asciiCode size: UTF-8 requires additional conversion code. However,
it allows one to use existing parsers without converting them to
std::wstring and such conversion is likely to create a
number of new instantiations.
There's no clear leader, but the last point seems important, so UTF-8
will be used.
Choosing the UTF-8 encoding allows the use of existing parsers,
because 7-bit ascii characters retain their values in UTF-8,
so searching for 7-bit strings is simple. However, there are
two subtle issues:
We need to assume the character literals use ascii encoding
and that inputs use Unicode encoding.A Unicode character (say '=') can be followed by 'composing
character' and the combination is not the same as just '=', so a
simple search for '=' might find the wrong character.
Neither of these issues appear to be critical in practice, since ascii is
almost universal encoding and since composing characters following '=' (and
other characters with special meaning to the library) are not likely to appear.
AcknowledgementsI'm very gratefull to all the people who helped with the development,
by discussion, fixes, and as users. It was pleasant
to see all that involvement, which made the library much better than it
would be otherwise.
In the early stages, the library was affected by discussions with
Gennadiy Rozental, William Kempf and Alexander Okhotin.
Hartmut Kaiser was the first person to try the library on his project
and send a number of suggestions and fixes.
The formal review lead to numerous comments and enhancements. Pavol
Droba helped with the option description semantic. Gennadiy Rozental has
criticised many aspects of the library which caused various simplifications.
Pavel Vozenilek did carefull review of the implementation. A number of
comments were made by:
David AbrahamsNeal D. BeckerMisha BergalJames CurranCarl DanielBeman DawesTanton GibbsHolger GrundHartmut KaiserPetr KocmidBaptiste LepilleurMarcelo E. MagallonChuck MessengerJohn TorjoMatthias TroyerDoug Gregor and Reece Dunn helped to resolve the issues with Boostbook
version of the documentation.
Even after review, a number of people have helped with further development:
Rob LievaartThorsten OttosenJoseph WuFerdinand PrantlMiro JurisicJohn MaddockJanusz PiwowarskiCharles BrockmanJonathan WakelyReferenceHeader <<ulink url="../../boost/program_options/cmdline.hpp">boost/program_options/cmdline.hpp</ulink>>namespace boost {
namespace program_options {
namespace command_line_style {
enum style_t;
}
}
}Type style_t3boost::program_options::command_line_style::style_tenum style_t { allow_long = 1, allow_short = allow_long << 1, allow_dash_for_short = allow_short << 1,
allow_slash_for_short = allow_dash_for_short << 1, long_allow_adjacent = allow_slash_for_short << 1, long_allow_next = long_allow_adjacent << 1,
short_allow_adjacent = long_allow_next << 1, short_allow_next = short_allow_adjacent << 1, allow_sticky = short_allow_next << 1,
allow_guessing = allow_sticky << 1, case_insensitive = allow_guessing << 1, allow_long_disguise = case_insensitive << 1,
unix_style = (allow_short | short_allow_adjacent | short_allow_next
| allow_long | long_allow_adjacent | long_allow_next
| allow_sticky | allow_guessing
| allow_dash_for_short), default_style = unix_style };Header <<ulink url="../../boost/program_options/environment_iterator.hpp">boost/program_options/environment_iterator.hpp</ulink>>namespace boost {
class environment_iterator;
}Class environment_iterator3boost::environment_iteratorclass environment_iterator : public boost::eof_iterator< environment_iterator, std::pair< std::string, std::string > >
{
public:
// construct/copy/destruct
environment_iterator(char **);
environment_iterator();
// public member functionsvoid get() ;
};Description<anchor id="environment_iteratorconstruct-copy-destruct"/><computeroutput>environment_iterator</computeroutput> construct/copy/destructenvironment_iterator(char ** environment);environment_iterator();<anchor id="id355347-bb"/><computeroutput>environment_iterator</computeroutput> public member functionsvoidget() ;Header <<ulink url="../../boost/program_options/eof_iterator.hpp">boost/program_options/eof_iterator.hpp</ulink>>namespace boost {
template<typename Derived, typename ValueType> class eof_iterator;
}Class template eof_iterator3boost::eof_iteratortemplate<typename Derived, typename ValueType>
class eof_iterator {
public:
// construct/copy/destruct
eof_iterator();
// public member functions// protected member functionsValueType & value() ;
void found_eof() ;
// private member functionsvoid increment() ;
bool equal(const eof_iterator &) const;
const ValueType & dereference() const;
};DescriptionThe 'eof_iterator' class is useful for constructing forward iterators in cases where iterator extract data from some source and it's easy to detect 'eof' -- i.e. the situation where there's no data. One apparent example is reading lines from a file.Implementing such iterators using 'iterator_facade' directly would require to create class with three core operation, a couple of constructors. When using 'eof_iterator', the derived class should define only one method to get new value, plus a couple of constructors.The basic idea is that iterator has 'eof' bit. Two iterators are equal only if both have their 'eof' bits set. The 'get' method either obtains the new value or sets the 'eof' bit.Specifically, derived class should define:1. A default constructor, which creates iterator with 'eof' bit set. The constructor body should call 'found_eof' method defined here. 2. Some other constructor. It should initialize some 'data pointer' used in iterator operation and then call 'get'. 3. The 'get' method. It should operate this way:look at some 'data pointer' to see if new element is available; if not, it should call 'found_eof'.extract new element and store it at location returned by the 'value' method.advance the data pointer.Essentially, the 'get' method has the functionality of both 'increment' and 'dereference'. It's very good for the cases where data extraction implicitly moves data pointer, like for stream operation. <anchor id="eof_iteratorconstruct-copy-destruct"/><computeroutput>eof_iterator</computeroutput> construct/copy/destructeof_iterator();<anchor id="id355116-bb"/><computeroutput>eof_iterator</computeroutput> public member functions<anchor id="id409557-bb"/><computeroutput>eof_iterator</computeroutput> protected member functionsValueType &value() ;Returns the reference which should be used by derived class to store the next value. voidfound_eof() ;Should be called by derived class to indicate that it can't produce next element. <anchor id="id356130-bb"/><computeroutput>eof_iterator</computeroutput> private member functionsvoidincrement() ;boolequal(const eof_iterator & other) const;const ValueType &dereference() const;Header <<ulink url="../../boost/program_options/errors.hpp">boost/program_options/errors.hpp</ulink>>namespace boost {
namespace program_options {
class error;
class invalid_syntax;
class unknown_option;
class ambiguous_option;
class multiple_values;
class multiple_occurrences;
class validation_error;
class invalid_option_value;
class too_many_positional_options_error;
class too_few_positional_options_error;
class invalid_command_line_syntax;
class invalid_command_line_style;
}
}Class error3boost::program_options::errorclass error {
public:
// construct/copy/destruct
error(const std::string &);
// public member functions
};DescriptionBase class for all errors in the library. <anchor id="errorconstruct-copy-destruct"/><computeroutput>error</computeroutput> construct/copy/destructerror(const std::string & what);<anchor id="id408913-bb"/><computeroutput>error</computeroutput> public member functionsClass invalid_syntax3boost::program_options::invalid_syntaxclass invalid_syntax : public boost::program_options::error {
public:
// construct/copy/destruct
invalid_syntax(const std::string &, const std::string &);
~invalid_syntax();
// public member functions
std::string tokens;
std::string msg;
};Description<anchor id="invalid_syntaxconstruct-copy-destruct"/><computeroutput>invalid_syntax</computeroutput> construct/copy/destructinvalid_syntax(const std::string & tokens, const std::string & msg);~invalid_syntax();<anchor id="id443182-bb"/><computeroutput>invalid_syntax</computeroutput> public member functionsClass unknown_option3boost::program_options::unknown_optionclass unknown_option : public boost::program_options::error {
public:
// construct/copy/destruct
unknown_option(const std::string &);
// public member functions
};DescriptionClass thrown when option name is not recognized. <anchor id="unknown_optionconstruct-copy-destruct"/><computeroutput>unknown_option</computeroutput> construct/copy/destructunknown_option(const std::string & name);<anchor id="id218507-bb"/><computeroutput>unknown_option</computeroutput> public member functionsClass ambiguous_option3boost::program_options::ambiguous_optionclass ambiguous_option : public boost::program_options::error {
public:
// construct/copy/destruct
ambiguous_option(const std::string &, const std::vector< std::string > &);
~ambiguous_option();
// public member functions
std::vector< std::string > alternatives;
};DescriptionClass thrown when there's ambiguity amoung several possible options. <anchor id="ambiguous_optionconstruct-copy-destruct"/><computeroutput>ambiguous_option</computeroutput> construct/copy/destructambiguous_option(const std::string & name,
const std::vector< std::string > & alternatives);~ambiguous_option();<anchor id="id375072-bb"/><computeroutput>ambiguous_option</computeroutput> public member functionsClass multiple_values3boost::program_options::multiple_valuesclass multiple_values : public boost::program_options::error {
public:
// construct/copy/destruct
multiple_values(const std::string &);
// public member functions
};DescriptionClass thrown when there are several option values, but user called a method which cannot return them all. <anchor id="multiple_valuesconstruct-copy-destruct"/><computeroutput>multiple_values</computeroutput> construct/copy/destructmultiple_values(const std::string & what);<anchor id="id415576-bb"/><computeroutput>multiple_values</computeroutput> public member functionsClass multiple_occurrences3boost::program_options::multiple_occurrencesclass multiple_occurrences : public boost::program_options::error {
public:
// construct/copy/destruct
multiple_occurrences(const std::string &);
// public member functions
};DescriptionClass thrown when there are several occurrences of an option, but user called a method which cannot return them all. <anchor id="multiple_occurrencesconstruct-copy-destruct"/><computeroutput>multiple_occurrences</computeroutput> construct/copy/destructmultiple_occurrences(const std::string & what);<anchor id="id365068-bb"/><computeroutput>multiple_occurrences</computeroutput> public member functionsClass validation_error3boost::program_options::validation_errorclass validation_error : public boost::program_options::error {
public:
// construct/copy/destruct
validation_error(const std::string &);
~validation_error();
// public member functionsvoid set_option_name(const std::string &) ;
// private member functionsconstchar * what() const;
};DescriptionClass thrown when value of option is incorrect. <anchor id="validation_errorconstruct-copy-destruct"/><computeroutput>validation_error</computeroutput> construct/copy/destructvalidation_error(const std::string & what);~validation_error();<anchor id="id352641-bb"/><computeroutput>validation_error</computeroutput> public member functionsvoidset_option_name(const std::string & option) ;<anchor id="id337074-bb"/><computeroutput>validation_error</computeroutput> private member functionsconstchar *what() const;Class invalid_option_value3boost::program_options::invalid_option_valueclass invalid_option_value
: : public boost::program_options::validation_error
{
public:
// construct/copy/destruct
invalid_option_value(const std::string &);
invalid_option_value(const std::wstring &);
// public member functions
};Description<anchor id="invalid_option_valueconstruct-copy-destruct"/><computeroutput>invalid_option_value</computeroutput> construct/copy/destructinvalid_option_value(const std::string & value);invalid_option_value(const std::wstring & value);<anchor id="id346387-bb"/><computeroutput>invalid_option_value</computeroutput> public member functionsClass too_many_positional_options_error3boost::program_options::too_many_positional_options_errorclass too_many_positional_options_error
: : public boost::program_options::error
{
public:
// construct/copy/destruct
too_many_positional_options_error(const std::string &);
// public member functions
};DescriptionClass thrown when there are too many positional options. <anchor id="id278842construct-copy-destruct"/><computeroutput>too_many_positional_options_error</computeroutput> construct/copy/destructtoo_many_positional_options_error(const std::string & what);<anchor id="id277956-bb"/><computeroutput>too_many_positional_options_error</computeroutput> public member functionsClass too_few_positional_options_error3boost::program_options::too_few_positional_options_errorclass too_few_positional_options_error
: : public boost::program_options::error
{
public:
// construct/copy/destruct
too_few_positional_options_error(const std::string &);
// public member functions
};DescriptionClass thrown when there are too few positional options. <anchor id="id436306construct-copy-destruct"/><computeroutput>too_few_positional_options_error</computeroutput> construct/copy/destructtoo_few_positional_options_error(const std::string & what);<anchor id="id345762-bb"/><computeroutput>too_few_positional_options_error</computeroutput> public member functionsClass invalid_command_line_syntax3boost::program_options::invalid_command_line_syntaxclass invalid_command_line_syntax {
public:
// construct/copy/destruct
invalid_command_line_syntax(const std::string &, kind_t);
// public member functionskind_t kind() const;
// protected static functionsstd::string error_message(kind_t) ;
};Description<anchor id="id233214construct-copy-destruct"/><computeroutput>invalid_command_line_syntax</computeroutput> construct/copy/destructinvalid_command_line_syntax(const std::string & tokens, kind_t kind);<anchor id="id279856-bb"/><computeroutput>invalid_command_line_syntax</computeroutput> public member functionskind_tkind() const;<anchor id="id362648-bb"/><computeroutput>invalid_command_line_syntax</computeroutput> protected static functionsstd::stringerror_message(kind_t kind) ;Class invalid_command_line_style3boost::program_options::invalid_command_line_styleclass invalid_command_line_style : public boost::program_options::error {
public:
// construct/copy/destruct
invalid_command_line_style(const std::string &);
// public member functions
};Description<anchor id="invalid_command_line_styleconstruct-copy-destruct"/><computeroutput>invalid_command_line_style</computeroutput> construct/copy/destructinvalid_command_line_style(const std::string & msg);<anchor id="id387860-bb"/><computeroutput>invalid_command_line_style</computeroutput> public member functionsHeader <<ulink url="../../boost/program_options/option.hpp">boost/program_options/option.hpp</ulink>>namespace boost {
namespace program_options {
template<typename charT> class basic_option;
typedef basic_option< char > option;
typedef basic_option< wchar_t > woption;
}
}Class template basic_option3boost::program_options::basic_optiontemplate<typename charT>
class basic_option {
public:
// construct/copy/destruct
basic_option();
basic_option(const std::string &, const std::vector< std::string > &);
// public member functions
std::string string_key;
int position_key;
std::vector< std::basic_string< charT > > value;
};DescriptionOption found in input source. Contains a key and a value. The key, in turn, can be a string (name of an option), or an integer (position in input source) -- in case no name is specified. The latter is only possible for command line. The template parameter specifies the type of char used for storing the option's value. <anchor id="basic_optionconstruct-copy-destruct"/><computeroutput>basic_option</computeroutput> construct/copy/destructbasic_option();basic_option(const std::string & string_key,
const std::vector< std::string > & value);<anchor id="id430785-bb"/><computeroutput>basic_option</computeroutput> public member functionsHeader <<ulink url="../../boost/program_options/options_description.hpp">boost/program_options/options_description.hpp</ulink>>namespace boost {
namespace program_options {
class option_description;
class options_description_easy_init;
class options_description;
class duplicate_option_error;
}
}Class option_description3boost::program_options::option_descriptionclass option_description {
public:
// construct/copy/destruct
option_description();
option_description(constchar *, const value_semantic *);
option_description(constchar *, const value_semantic *, constchar *);
~option_description();
// public member functionsconst std::string & short_name() const;
const std::string & long_name() const;
const std::string & description() const;
shared_ptr< const value_semantic > semantic() const;
std::string format_name() const;
std::string format_parameter() const;
// private member functionsoption_description & name(constchar *) ;
};DescriptionDescribes one possible command line/config file option. There are two kinds of properties of an option. First describe it syntactically and are used only to validate input. Second affect interpretation of the option, for example default value for it or function that should be called when the value is finally known. Routines which perform parsing never use second kind of properties -- they are side effect free. options_description <anchor id="option_descriptionconstruct-copy-destruct"/><computeroutput>option_description</computeroutput> construct/copy/destructoption_description();option_description(constchar * name, const value_semantic * s);Initializes the object with the passed data.Note: it would be nice to make the second parameter auto_ptr, to explicitly pass ownership. Unfortunately, it's often needed to create objects of types derived from 'value_semantic': options_description d; d.add_options()("a", parameter<int>("n")->default_value(1)); Here, the static type returned by 'parameter' should be derived from value_semantic.Alas, derived->base conversion for auto_ptr does not really work, see http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2000/n1232.pdf http://std.dkuug.dk/jtc1/sc22/wg21/docs/cwg_defects.html#84So, we have to use plain old pointers. Besides, users are not expected to use the constructor directly.The 'name' parameter is interpreted by the following rules:if there's no "," character in 'name', it specifies long nameotherwise, the part before "," specifies long name and the part after -- long name. option_description(constchar * name, const value_semantic * s,
constchar * description);Initializes the class with the passed data. ~option_description();<anchor id="id406814-bb"/><computeroutput>option_description</computeroutput> public member functionsconst std::string &short_name() const;const std::string &long_name() const;const std::string &description() const;shared_ptr< const value_semantic >semantic() const;std::stringformat_name() const;std::stringformat_parameter() const;Return the parameter name and properties, formatted suitably for usage message. <anchor id="id319434-bb"/><computeroutput>option_description</computeroutput> private member functionsoption_description &name(constchar * name) ;Class options_description_easy_init3boost::program_options::options_description_easy_initclass options_description_easy_init {
public:
// construct/copy/destruct
options_description_easy_init(options_description *);
// public member functionsoptions_description_easy_init &operator()(constchar *, constchar *) ;
options_description_easy_init &operator()(constchar *, const value_semantic *) ;
options_description_easy_init &operator()(constchar *, const value_semantic *, constchar *) ;
};DescriptionClass which provides convenient creation syntax to option_description. <anchor id="id367899construct-copy-destruct"/><computeroutput>options_description_easy_init</computeroutput> construct/copy/destructoptions_description_easy_init(options_description * owner);<anchor id="id415060-bb"/><computeroutput>options_description_easy_init</computeroutput> public member functionsoptions_description_easy_init &operator()(constchar * name, constchar * description) ;options_description_easy_init &operator()(constchar * name, const value_semantic * s) ;options_description_easy_init &operator()(constchar * name, const value_semantic * s,
constchar * description) ;Class options_description3boost::program_options::options_descriptionclass options_description {
public:
// construct/copy/destruct
options_description();
options_description(const std::string &);
// public member functionsvoid add(shared_ptr< option_description >) ;
options_description & add(const options_description &) ;
options_description_easy_init add_options() ;
unsigned count(const std::string &) const;
unsigned count_approx(const std::string &) const;
const option_description & find(const std::string &) const;
const option_description & find_approx(const std::string &) const;
std::set< std::string > keys() const;
std::set< std::string > primary_keys() const;
std::set< std::string > approximations(const std::string &) const;
void print(std::ostream &) const;
// private member functionsapproximation_range find_approximation(const std::string &) const;
};DescriptionA set of option descriptions. This provides convenient interface for adding new option (the add_options) method, and facilities to search for options by name.See here for option adding interface discussion. option_description <anchor id="options_descriptionconstruct-copy-destruct"/><computeroutput>options_description</computeroutput> construct/copy/destructoptions_description();Creates the instance. options_description(const std::string & caption);Creates the instance. The 'caption' parameter gives the name of this 'options_description' instance. Primarily useful for output. <anchor id="id247472-bb"/><computeroutput>options_description</computeroutput> public member functionsvoidadd(shared_ptr< option_description > desc) ;Adds new variable description. Throws duplicate_variable_error if either short or long name matches that of already present one. options_description &add(const options_description & desc) ;Adds a group of option description. This has the same effect as adding all option_descriptions in 'desc' individually, except that output operator will show a separate group. Returns *this. options_description_easy_initadd_options() ;Returns an object of implementation-defined type suitable for adding options to options_description. The returned object will have overloaded operator() with parameter type matching 'option_description' constructors. Calling the operator will create new option_description instance and add it. unsignedcount(const std::string & name) const;Count the number of option descriptions with given name. Returns 0 or 1. The 'name' parameter can be either name of long option, and short option prefixed by '-'. unsignedcount_approx(const std::string & prefix) const;Count the number of descriptions having the given string as prefix. This makes sense only for long options. const option_description &find(const std::string & name) const;Returns description given a name.
Requirescount(name) == 1 const option_description &find_approx(const std::string & prefix) const;Returns description given a prefix. Throws
Requirescount_approx(name) == 1 std::set< std::string >keys() const;std::set< std::string >primary_keys() const;For each option description stored, contains long name if not empty, if it is empty, short name is returned. std::set< std::string >approximations(const std::string & prefix) const;voidprint(std::ostream & os) const;Output 'desc' to the specified stream, calling 'f' to output each option_description element. <anchor id="id262614-bb"/><computeroutput>options_description</computeroutput> private member functionsapproximation_rangefind_approximation(const std::string & prefix) const;Class duplicate_option_error3boost::program_options::duplicate_option_errorclass duplicate_option_error : public boost::program_options::error {
public:
// construct/copy/destruct
duplicate_option_error(const std::string &);
// public member functions
};DescriptionClass thrown when duplicate option description is found. <anchor id="duplicate_option_errorconstruct-copy-destruct"/><computeroutput>duplicate_option_error</computeroutput> construct/copy/destructduplicate_option_error(const std::string & what);<anchor id="id414999-bb"/><computeroutput>duplicate_option_error</computeroutput> public member functionsHeader <<ulink url="../../boost/program_options/parsers.hpp">boost/program_options/parsers.hpp</ulink>>namespace boost {
namespace program_options {
template<typename charT> class basic_parsed_options;
template<> class basic_parsed_options<wchar_t>;
class common_command_line_parser;
template<typename charT> class basic_command_line_parser;
typedef basic_parsed_options< char > parsed_options;
typedef basic_parsed_options< wchar_t > wparsed_options;
typedef function1< std::pair< std::string, std::string >, const std::string & > ext_parser;
typedef basic_command_line_parser< char > command_line_parser;
typedef basic_command_line_parser< wchar_t > wcommand_line_parser;
template<typename charT>
basic_parsed_options< charT >
parse_command_line(int, charT *, const options_description &, int = 0,
function1< std::pair< std::string, std::string >, const std::string & > = ext_parser());
template<typename charT>
BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options< charT >
parse_config_file(std::basic_istream< charT > &,
const options_description &);
BOOST_PROGRAM_OPTIONS_DECL parsed_options
parse_environment(const options_description &,
const function1< std::string, std::string > &);
BOOST_PROGRAM_OPTIONS_DECL parsed_options
parse_environment(const options_description &, const std::string &);
BOOST_PROGRAM_OPTIONS_DECL parsed_options
parse_environment(const options_description &, constchar *);
}
}Class template basic_parsed_options3boost::program_options::basic_parsed_optionstemplate<typename charT>
class basic_parsed_options {
public:
// construct/copy/destruct
basic_parsed_options(const options_description *);
// public member functions
std::vector< basic_option< charT > > options;
const options_description * description;
};DescriptionResults of parsing an input source. The primary use of this class is passing information from parsers component to value storage component. This class does not makes much sense itself. <anchor id="basic_parsed_optionsconstruct-copy-destruct"/><computeroutput>basic_parsed_options</computeroutput> construct/copy/destructbasic_parsed_options(const options_description * description);<anchor id="id251453-bb"/><computeroutput>basic_parsed_options</computeroutput> public member functionsSpecializationsClass basic_parsed_options<wchar_t>Class basic_parsed_options<wchar_t>3boost::program_options::basic_parsed_options<wchar_t>class basic_parsed_options<wchar_t> {
public:
// public member functions basic_parsed_options(const basic_parsed_options< char > &) ;
std::vector< basic_option< wchar_t > > options;
const options_description * description;
basic_parsed_options< char > utf8_encoded_options;
};DescriptionSpecialization of basic_parsed_options which:provides convenient conversion from basic_parsed_options<char>stores the passed char-based options for later use. <anchor id="id274196-bb"/><computeroutput>basic_parsed_options</computeroutput> public member functionsbasic_parsed_options(const basic_parsed_options< char > & po) ;Constructs wrapped options from options in UTF8 encoding. Class common_command_line_parser3boost::program_options::common_command_line_parserclass common_command_line_parser {
public:
// construct/copy/destruct
common_command_line_parser(const std::vector< std::string > &);
// public member functionsparsed_options run() const;
};DescriptionCharacter-type independent command line parser. <anchor id="common_command_line_parserconstruct-copy-destruct"/><computeroutput>common_command_line_parser</computeroutput> construct/copy/destructcommon_command_line_parser(const std::vector< std::string > & args);<anchor id="id412751-bb"/><computeroutput>common_command_line_parser</computeroutput> public member functionsparsed_optionsrun() const;Parses the command line and returns parsed options in internal encoding. Class template basic_command_line_parser3boost::program_options::basic_command_line_parsertemplate<typename charT>
class basic_command_line_parser
: : private boost::program_options::common_command_line_parser
{
public:
// construct/copy/destruct
basic_command_line_parser(const std::vector< std::basic_string< charT > > &);
basic_command_line_parser(int, charT *);
// public member functionsbasic_command_line_parser & options(const options_description &) ;
basic_command_line_parser &
positional(const positional_options_description &) ;
basic_command_line_parser & style(int) ;
basic_command_line_parser & extra_parser(ext_parser) ;
basic_parsed_options< charT > run() const;
};DescriptionCommand line parser.The class allows one to specify all the information needed for parsing and to parser the parse the command line. It is primarily needed to emulate named function parameters -- a regular function with 5 parameters will be hard to use and creating overloads with a smaller nuber of parameters will be confusing.For the most common case, the function parse_command_line is a better alternative. <anchor id="basic_command_line_parserconstruct-copy-destruct"/><computeroutput>basic_command_line_parser</computeroutput> construct/copy/destructbasic_command_line_parser(const std::vector< std::basic_string< charT > > & args);Creates a command line parser for the specified arguments list. The 'args' parameter should not include program name. basic_command_line_parser(int argc, charT * argv);Creates a command line parser for the specified arguments list. The parameter should be the same as passes to 'main'. <anchor id="id397948-bb"/><computeroutput>basic_command_line_parser</computeroutput> public member functionsbasic_command_line_parser &options(const options_description & desc) ;Sets options descriptions to use. basic_command_line_parser &positional(const positional_options_description & desc) ;Sets positional options description to use. basic_command_line_parser &style(int ) ;Sets the command line style. basic_command_line_parser &extra_parser(ext_parser ) ;Sets the extra parsers. basic_parsed_options< charT >run() const;Parses the command line and returns parsed options in internal encoding. Function template parse_command_line3boost::program_options::parse_command_linetemplate<typename charT>
basic_parsed_options< charT >
parse_command_line(int argc, charT * argv, const options_description & ,
int style = 0,
function1< std::pair< std::string, std::string >, const std::string & > ext = ext_parser());DescriptionCreates instance of 'command_line_parser', passes parameters to it, and returns the result of calling the 'run' method. Function template parse_config_file3boost::program_options::parse_config_filetemplate<typename charT>
BOOST_PROGRAM_OPTIONS_DECL basic_parsed_options< charT >
parse_config_file(std::basic_istream< charT > & ,
const options_description & );DescriptionParse a config file. Function parse_environment3boost::program_options::parse_environmentBOOST_PROGRAM_OPTIONS_DECL parsed_options
parse_environment(const options_description & ,
const function1< std::string, std::string > & name_mapper);DescriptionParse environment.For each environment variable, the 'name_mapper' function is called to obtain the option name. If it returns empty string, the variable is ignored.This is done since naming of environment variables is typically different from the naming of command line options. Function parse_environment3boost::program_options::parse_environmentBOOST_PROGRAM_OPTIONS_DECL parsed_options
parse_environment(const options_description & , const std::string & prefix);
BOOST_PROGRAM_OPTIONS_DECL parsed_options
parse_environment(const options_description & , constchar * prefix);DescriptionParse environment.Takes all environment variables which start with 'prefix'. The option name is obtained from variable name by removing the prefix and converting the remaining string into lower case. Header <<ulink url="../../boost/program_options/positional_options.hpp">boost/program_options/positional_options.hpp</ulink>>namespace boost {
namespace program_options {
class positional_options_description;
}
}Class positional_options_description3boost::program_options::positional_options_descriptionclass positional_options_description {
public:
// construct/copy/destruct
positional_options_description();
// public member functionsvoid add(constchar *, int) ;
unsigned max_total_count() const;
const std::string & name_for_position(unsigned) const;
};DescriptionDescribes positional options.The class allows to guess option names for positional options, which are specified on the command line and are identified by the position. The class uses the information provided by the user to associate a name with every positional option, or tell that no name is known.The primary assumption is that only the relative order of the positional options themselves matters, and that any interleaving ordinary options don't affect interpretation of positional options.The user initializes the class by specifying that first N positional options should be given the name X1, following M options should be given the name X2 and so on. <anchor id="id277022construct-copy-destruct"/><computeroutput>positional_options_description</computeroutput> construct/copy/destructpositional_options_description();<anchor id="id228419-bb"/><computeroutput>positional_options_description</computeroutput> public member functionsvoidadd(constchar * name, int max_count) ;Species that up to 'max_count' next positional options should be given the 'name'. The value of '-1' means 'unlimited'. No calls to 'add' can be made after call with 'max_value' equal to '-1'. unsignedmax_total_count() const;Returns the maximum number of positional options that can be present. Can return numeric_limits<unsigned>::max() to indicate unlimited number. const std::string &name_for_position(unsigned position) const;Returns the name that should be associated with positional options at 'position'. Precondition: position < max_total_count() Header <<ulink url="../../boost/program_options/value_semantic.hpp">boost/program_options/value_semantic.hpp</ulink>>namespace boost {
namespace program_options {
class value_semantic;
template<typename charT> class value_semantic_codecvt_helper;
template<> class value_semantic_codecvt_helper<char>;
template<> class value_semantic_codecvt_helper<wchar_t>;
class untyped_value;
template<typename T, typename charT = char> class typed_value;
template<typename T> typed_value< T > * value();
template<typename T> typed_value< T > * value(T *);
template<typename T> typed_value< T, wchar_t > * wvalue();
template<typename T> typed_value< T, wchar_t > * wvalue(T *);
BOOST_PROGRAM_OPTIONS_DECL typed_value< bool > * bool_switch();
BOOST_PROGRAM_OPTIONS_DECL typed_value< bool > * bool_switch(bool *);
}
}Class value_semantic3boost::program_options::value_semanticclass value_semantic {
public:
// construct/copy/destruct
~value_semantic();
// public member functionsvirtual std::string name() const;
virtualbool is_zero_tokens() const;
virtualbool is_composing() const;
virtualbool is_implicit() const;
virtualbool is_multitoken() const;
virtualvoid
parse(boost::any &, const std::vector< std::string > &, bool) const;
virtualbool apply_default(boost::any &) const;
virtualvoid notify(const boost::any &) const;
};DescriptionClass which specifies how the option's value is to be parsed and converted into C++ types. <anchor id="value_semanticconstruct-copy-destruct"/><computeroutput>value_semantic</computeroutput> construct/copy/destruct~value_semantic();<anchor id="id322469-bb"/><computeroutput>value_semantic</computeroutput> public member functionsvirtual std::stringname() const;Returns the name of the option. The name is only meaningful for automatic help message. virtualboolis_zero_tokens() const;Returns true if value cannot be specified in source at all. Other methods can still set the value somehow, but user can't affect it. virtualboolis_composing() const;Returns true if values from different sources should be composed. Otherwise, value from the first source is used and values from other sources are discarded. virtualboolis_implicit() const;Returns true if explicit value of an option can be omitted. virtualboolis_multitoken() const;Returns true if value can span several token in input source. virtualvoidparse(boost::any & value_store, const std::vector< std::string > & new_tokens,
bool utf8) const;Parses a group of tokens that specify a value of option. Stores the result in 'value_store', using whatever representation is desired. May be be called several times if value of the same option is specified more than once. virtualboolapply_default(boost::any & value_store) const;Called to assign default value to 'value_store'. Returns true if default value is assigned, and false if no default value exists. virtualvoidnotify(const boost::any & value_store) const;Called when final value of an option is determined. Class template value_semantic_codecvt_helper3boost::program_options::value_semantic_codecvt_helpertemplate<typename charT>
class value_semantic_codecvt_helper {
public:
};DescriptionHelper class which perform necessary character conversions in the 'parse' method and forwards the data further. SpecializationsClass value_semantic_codecvt_helper<char>Class value_semantic_codecvt_helper<wchar_t>Class value_semantic_codecvt_helper<char>3boost::program_options::value_semantic_codecvt_helper<char>class value_semantic_codecvt_helper<char> {
public:
// protected member functionsvirtualvoid xparse(boost::any &, const std::vector< std::string > &) const;
// private member functionsvoid parse(boost::any &, const std::vector< std::string > &, bool) const;
};Description<anchor id="id275200-bb"/><computeroutput>value_semantic_codecvt_helper</computeroutput> protected member functionsvirtualvoidxparse(boost::any & value_store,
const std::vector< std::string > & new_tokens) const;<anchor id="id226527-bb"/><computeroutput>value_semantic_codecvt_helper</computeroutput> private member functionsvoidparse(boost::any & value_store,
const std::vector< std::string > & new_tokens, bool utf8) const;Class value_semantic_codecvt_helper<wchar_t>3boost::program_options::value_semantic_codecvt_helper<wchar_t>class value_semantic_codecvt_helper<wchar_t>
: : public boost::program_options::value_semantic
{
public:
// protected member functionsvirtualvoid xparse(boost::any &, const std::vector< std::wstring > &) const;
// private member functionsvoid parse(boost::any &, const std::vector< std::string > &, bool) const;
};Description<anchor id="id306954-bb"/><computeroutput>value_semantic_codecvt_helper</computeroutput> protected member functionsvirtualvoidxparse(boost::any & value_store,
const std::vector< std::wstring > & new_tokens) const;<anchor id="id258112-bb"/><computeroutput>value_semantic_codecvt_helper</computeroutput> private member functionsvoidparse(boost::any & value_store,
const std::vector< std::string > & new_tokens, bool utf8) const;Class untyped_value3boost::program_options::untyped_valueclass untyped_value
: : public boost::program_options::value_semantic_codecvt_helper< charT >
{
public:
// construct/copy/destruct
untyped_value(bool = false);
// public member functionsstd::string name() const;
bool is_zero_tokens() const;
bool is_composing() const;
bool is_implicit() const;
bool is_multitoken() const;
void xparse(boost::any &, const std::vector< std::string > &) const;
bool apply_default(boost::any &) const;
void notify(const boost::any &) const;
};DescriptionClass which specifies a simple handling of a value: the value will have string type and only one token is allowed. <anchor id="untyped_valueconstruct-copy-destruct"/><computeroutput>untyped_value</computeroutput> construct/copy/destructuntyped_value(bool zero_tokens = false);<anchor id="id415126-bb"/><computeroutput>untyped_value</computeroutput> public member functionsstd::stringname() const;boolis_zero_tokens() const;boolis_composing() const;boolis_implicit() const;boolis_multitoken() const;voidxparse(boost::any & value_store,
const std::vector< std::string > & new_tokens) const;If 'value_store' is already initialized, or new_tokens has more than one elements, throws. Otherwise, assigns the first string from 'new_tokens' to 'value_store', without any modifications. boolapply_default(boost::any & ) const;Does nothing. voidnotify(const boost::any & ) const;Does nothing. Class template typed_value3boost::program_options::typed_valuetemplate<typename T, typename charT = char>
class typed_value
: : public boost::program_options::value_semantic_codecvt_helper< charT >
{
public:
// construct/copy/destruct
typed_value(T *);
// public member functionstyped_value * default_value(const T &) ;
typed_value * default_value(const T &, const std::string &) ;
typed_value * notifier(function1< void, const T & >) ;
typed_value * composing() ;
typed_value * implicit() ;
typed_value * multitoken() ;
typed_value * zero_tokens() ;
std::string name() const;
bool is_zero_tokens() const;
bool is_composing() const;
bool is_implicit() const;
bool is_multitoken() const;
void xparse(boost::any &, const std::vector< std::basic_string< charT > > &) const;
virtualbool apply_default(boost::any &) const;
void notify(const boost::any &) const;
};DescriptionClass which handles value of a specific type. <anchor id="typed_valueconstruct-copy-destruct"/><computeroutput>typed_value</computeroutput> construct/copy/destructtyped_value(T * store_to);Ctor. The 'store_to' parameter tells where to store the value when it's known. The parameter can be NULL. <anchor id="id429890-bb"/><computeroutput>typed_value</computeroutput> public member functionstyped_value *default_value(const T & v) ;Specifies default value, which will be used if none is explicitly specified. The type 'T' should provide operator<< for ostream. typed_value *default_value(const T & v, const std::string & textual) ;Specifies default value, which will be used if none is explicitly specified. Unlike the above overload, the type 'T' need not provide operator<< for ostream, but textual representation of default value must be provided by the user. typed_value *notifier(function1< void, const T & > f) ;Specifies a function to be called when the final value is determined. typed_value *composing() ;Specifies that the value is composing. See the 'is_composing' method for explanation. typed_value *implicit() ;Specifies that the value is implicit. typed_value *multitoken() ;Specifies that the value can span multiple tokens. typed_value *zero_tokens() ;std::stringname() const;boolis_zero_tokens() const;boolis_composing() const;boolis_implicit() const;boolis_multitoken() const;voidxparse(boost::any & value_store,
const std::vector< std::basic_string< charT > > & new_tokens) const;Creates an instance of the 'validator' class and calls its operator() to perform athe ctual conversion. virtualboolapply_default(boost::any & value_store) const;If default value was specified via previous call to 'default_value', stores that value into 'value_store'. Returns true if default value was stored. voidnotify(const boost::any & value_store) const;If an address of variable to store value was specified when creating *this, stores the value there. Otherwise, does nothing. Function value3boost::program_options::valuetemplate<typename T> typed_value< T > * value();
template<typename T> typed_value< T > * value(T * v);DescriptionCreates a typed_value<T> instance. This function is the primary method to create value_semantic instance for a specific type, which can later be passed to 'option_description' constructor. The second overload is used when it's additionally desired to store the value of option into program variable. Function wvalue3boost::program_options::wvaluetemplate<typename T> typed_value< T, wchar_t > * wvalue();
template<typename T> typed_value< T, wchar_t > * wvalue(T * v);DescriptionCreates a typed_value<T> instance. This function is the primary method to create value_semantic instance for a specific type, which can later be passed to 'option_description' constructor. Function bool_switch3boost::program_options::bool_switchBOOST_PROGRAM_OPTIONS_DECL typed_value< bool > * bool_switch();
BOOST_PROGRAM_OPTIONS_DECL typed_value< bool > * bool_switch(bool * v);DescriptionWorks the same way as the 'value<bool>' function, but the created value_semantic won't accept any explicit value. So, if the option is present on the command line, the value will be 'true'. Header <<ulink url="../../boost/program_options/variables_map.hpp">boost/program_options/variables_map.hpp</ulink>>namespace boost {
namespace program_options {
class variable_value;
class abstract_variables_map;
class variables_map;
BOOST_PROGRAM_OPTIONS_DECL void
store(const basic_parsed_options< char > &, variables_map &, bool = false);
BOOST_PROGRAM_OPTIONS_DECL void
store(const basic_parsed_options< wchar_t > &, variables_map &);
BOOST_PROGRAM_OPTIONS_DECL void notify(variables_map &);
}
}Class variable_value3boost::program_options::variable_valueclass variable_value {
public:
// construct/copy/destruct
variable_value();
variable_value(const boost::any &, bool);
// public member functionstemplate<typename T> const T & as() const;
template<typename T> T & as() ;
bool empty() const;
bool defaulted() const;
const boost::any & value() const;
boost::any & value() ;
};DescriptionClass holding value of option. Contains details about how the value is set and allows to conveniently obtain the value. <anchor id="variable_valueconstruct-copy-destruct"/><computeroutput>variable_value</computeroutput> construct/copy/destructvariable_value();variable_value(const boost::any & v, bool defaulted);<anchor id="id338122-bb"/><computeroutput>variable_value</computeroutput> public member functionstemplate<typename T> const T &as() const;If stored value if of type T, returns that value. Otherwise, throws boost::bad_any_cast exception. template<typename T> T &as() ;This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. boolempty() const;booldefaulted() const;Returns true if the value was not explicitly given, but has default value. const boost::any &value() const;Returns the contained value. boost::any &value() ;Returns the contained value. Class abstract_variables_map3boost::program_options::abstract_variables_mapclass abstract_variables_map {
public:
// construct/copy/destruct
abstract_variables_map();
abstract_variables_map(const abstract_variables_map *);
~abstract_variables_map();
// public member functionsconst variable_value &operator[](const std::string &) const;
void next(abstract_variables_map *) ;
// private member functionsvirtualconst variable_value & get(const std::string &) const;
};DescriptionImplements string->string mapping with convenient value casting facilities. <anchor id="abstract_variables_mapconstruct-copy-destruct"/><computeroutput>abstract_variables_map</computeroutput> construct/copy/destructabstract_variables_map();abstract_variables_map(const abstract_variables_map * next);~abstract_variables_map();<anchor id="id421775-bb"/><computeroutput>abstract_variables_map</computeroutput> public member functionsconst variable_value &operator[](const std::string & name) const;Obtains the value of variable 'name', from *this and possibly from the chain of variable maps.if there's no value in *this.if there's next variable map, returns value from itotherwise, returns empty valueif there's defaulted valueif there's next varaible map, which has a non-defauled value, return thatotherwise, return value from *thisif there's a non-defauled value, returns it. voidnext(abstract_variables_map * next) ;Sets next variable map, which will be used to find variables not found in *this. <anchor id="id225473-bb"/><computeroutput>abstract_variables_map</computeroutput> private member functionsvirtualconst variable_value &get(const std::string & name) const;Returns value of variable 'name' stored in *this, or empty value otherwise. Class variables_map3boost::program_options::variables_mapclass variables_map
: : public boost::program_options::abstract_variables_map
{
public:
// construct/copy/destruct
variables_map();
variables_map(const abstract_variables_map *);
// public member functionsconst variable_value &operator[](const std::string &) const;
// private member functionsconst variable_value & get(const std::string &) const;
};DescriptionConcrete variables map which store variables in real map. <anchor id="variables_mapconstruct-copy-destruct"/><computeroutput>variables_map</computeroutput> construct/copy/destructvariables_map();variables_map(const abstract_variables_map * next);<anchor id="id310840-bb"/><computeroutput>variables_map</computeroutput> public member functionsconst variable_value &operator[](const std::string & name) const;Obtains the value of variable 'name', from *this and possibly from the chain of variable maps.if there's no value in *this.if there's next variable map, returns value from itotherwise, returns empty valueif there's defaulted valueif there's next varaible map, which has a non-defauled value, return thatotherwise, return value from *thisif there's a non-defauled value, returns it. <anchor id="id361413-bb"/><computeroutput>variables_map</computeroutput> private member functionsconst variable_value &get(const std::string & name) const;Implementation of abstract_variables_map::get which does 'find' in *this. Function store3boost::program_options::storeBOOST_PROGRAM_OPTIONS_DECL void
store(const basic_parsed_options< char > & options, variables_map & m,
bool utf8 = false);DescriptionStores in 'm' all options that are defined in 'options'. If 'm' already has a non-defaulted value of an option, that value is not changed, even if 'options' specify some value. Function store3boost::program_options::storeBOOST_PROGRAM_OPTIONS_DECL void
store(const basic_parsed_options< wchar_t > & options, variables_map & m);DescriptionStores in 'm' all options that are defined in 'options'. If 'm' already has a non-defaulted value of an option, that value is not changed, even if 'options' specify some value. This is wide character variant. Function notify3boost::program_options::notifyBOOST_PROGRAM_OPTIONS_DECL void notify(variables_map & m);DescriptionRuns all 'notify' function for options in 'm'. Header <<ulink url="../../boost/program_options/version.hpp">boost/program_options/version.hpp</ulink>>
BOOST_PROGRAM_OPTIONS_VERSIONMacro BOOST_PROGRAM_OPTIONS_VERSION3BOOST_PROGRAM_OPTIONS_VERSIONBOOST_PROGRAM_OPTIONS_VERSIONDescriptionThe version of the source interface. The value will be incremented whenever a change is made which might cause compilation errors for existing code. JaakkoJärviPeterDimovDouglasGregorDaveAbrahams19992000Jaakko Järvi20012002Peter Dimov2002David AbrahamsPermission to copy, use, modify, sell and distribute this
software is granted provided this copyright notice appears in
all copies. This software is provided "as is" without express
or implied warranty, and with no claim as to its suitability for
any purpose.
Boost.RefIntroductionThe Ref library is a small library that is useful for passing
references to function templates (algorithms) that would usually
take copies of their arguments. It defines the class template
boost::reference_wrapper<T>,
the two functions
boost::ref and
boost::cref that return
instances of boost::reference_wrapper<T>, and the
two traits classes
boost::is_reference_wrapper<T>
and
boost::unwrap_reference<T>.The purpose of
boost::reference_wrapper<T> is to
contain a reference to an object of type T. It is primarily used to
"feed" references to function templates (algorithms) that take their
parameter by value.To support this usage,
boost::reference_wrapper<T> provides an implicit
conversion to T&. This usually allows the function
templates to work on references unmodified.boost::reference_wrapper<T> is
both CopyConstructible and Assignable (ordinary references are not
Assignable).The expression boost::ref(x)
returns a
boost::reference_wrapper<X>(x) where X
is the type of x. Similarly,
boost::cref(x) returns a
boost::reference_wrapper<X const>(x).The expression
boost::is_reference_wrapper<T>::value
is true if T is a reference_wrapper, and
false otherwise.The type-expression
boost::unwrap_reference<T>::type is T::type if T
is a reference_wrapper, T otherwise.ReferenceHeader <<ulink url="../../boost/ref.hpp">boost/ref.hpp</ulink>>namespace boost {
template<typename T> class reference_wrapper;
reference_wrapper<T> ref(T&);
reference_wrapper<T const> cref(T const&);
template<typename T> class is_reference_wrapper;
template<typename T> class unwrap_reference;
}Class template reference_wrapper3boost::reference_wrapper
Contains a reference to an object of type
T.
template<typename T>
class reference_wrapper {
public:
// typestypedef T type;
// construct/copy/destructexplicit reference_wrapper(T&);
// accessoperator T&() const;
T& get() const;
T* get_pointer() const;
};
// constructorsreference_wrapper<T> ref(T&);
reference_wrapper<T const> cref(T const&);Descriptionreference_wrapper
is primarily used to "feed" references to function templates
(algorithms) that take their parameter by value. It provides
an implicit conversion to
T&, which usually allows
the function templates to work on references
unmodified.<anchor id="reference_wrapperconstruct-copy-destruct"/><computeroutput>reference_wrapper</computeroutput> construct/copy/destructexplicitreference_wrapper(T& t);EffectsConstructs a
reference_wrapper
object that stores a reference to
t.ThrowsDoes not throw.<anchor id="id274636-bb"/><computeroutput>reference_wrapper</computeroutput> accessoperator T&() const;ReturnsThe stored reference.ThrowsDoes not throw.T&get() const;ReturnsThe stored reference.ThrowsDoes not throw.T*get_pointer() const;ReturnsA pointer to the object referenced by the stored reference.ThrowsDoes not throw.<anchor id="id376296-bb"/><computeroutput>reference_wrapper</computeroutput> constructorsreference_wrapper<T>ref(T& t);Returnsreference_wrapper<T>(t)ThrowsDoes not throw.reference_wrapper<T const>cref(T const& t);Returnsreference_wrapper<T const>(t)ThrowsDoes not throw.Class template is_reference_wrapper3boost::is_reference_wrapperDetermine if a type T is an instantiation of reference_wrapper.template<typename T>
class is_reference_wrapper {
public:
// static constantsstaticconstbool value = unspecified;
};DescriptionThe value static
constant will be true iff the
type T is a specialization of
reference_wrapper.Class template unwrap_reference3boost::unwrap_referenceFind the type in a reference_wrapper.template<typename T>
class unwrap_reference {
public:
// typestypedefunspecified type;
};DescriptionThe typedef type is
T::type if
T is a
reference_wrapper,
T otherwise.Acknowledgementsref and cref
were originally part of the Tuple library
by Jaakko Järvi. They were "promoted to boost:: status" by
Peter Dimov because they are generally useful. Douglas Gregor and
Dave Abrahams contributed
is_reference_wrapper and
unwrap_reference.DouglasGregor2001200220032004Douglas GregorUse, modification and distribution is 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)Boost.SignalsIntroductionThe Boost.Signals library is an implementation of a managed
signals and slots system. Signals represent callbacks with multiple
targets, and are also called publishers or events in similar
systems. Signals are connected to some set of slots, which are
callback receivers (also called event targets or subscribers), which
are called when the signal is "emitted."Signals and slots are managed, in that signals and slots (or,
more properly, objects that occur as part of the slots) track all
connections and are capable of automatically disconnecting signal/slot
connections when either is destroyed. This enables the user to make
signal/slot connections without expending a great effort to manage the
lifetimes of those connections with regard to the lifetimes of all
objects involved.When signals are connected to multiple slots, there is a
question regarding the relationship between the return values of the
slots and the return value of the signals. Boost.Signals allows the
user to specify the manner in which multiple return values are
combined.TutorialHow to Read this TutorialThis tutorial is not meant to be read linearly. Its top-level
structure roughly separates different concepts in the library
(e.g., handling calling multiple slots, passing values to and from
slots) and in each of these concepts the basic ideas are presented
first and then more complex uses of the library are described
later. Each of the sections is marked Beginner,
Intermediate, or Advanced to help guide the
reader. The Beginner sections include information that all
library users should know; one can make good use of the Signals
library after having read only the Beginner sections. The
Intermediate sections build on the Beginner
sections with slightly more complex uses of the library. Finally,
the Advanced sections detail very advanced uses of the
Signals library, that often require a solid working knowledge of
the Beginner and Intermediate topics; most users
will not need to read the Advanced sections.Compatibility NoteBoost.Signals has two syntactical forms: the preferred form and
the compatibility form. The preferred form fits more closely with the
C++ language and reduces the number of separate template parameters
that need to be considered, often improving readability; however, the
preferred form is not supported on all platforms due to compiler
bugs. The compatible form will work on all compilers supported by
Boost.Signals. Consult the table below to determine which syntactic
form to use for your compiler. Users of Boost.Function, please note
that the preferred syntactic form in Signals is equivalent to that of
Function's preferred syntactic form.If your compiler does not appear in this list, please try the
preferred syntax and report your results to the Boost list so that
we can keep this table up-to-date.Preferred syntaxPortable syntaxGNU C++ 2.95.x, 3.0.x, 3.1.xComeau C++ 4.2.45.2SGI MIPSpro 7.3.0Intel C++ 5.0, 6.0Compaq's cxx 6.2Microsoft Visual C++ 7.1Any compiler supporting the preferred syntaxMicrosoft Visual C++ 6.0, 7.0Borland C++ 5.5.1Sun WorkShop 6 update 2 C++ 5.3Metrowerks CodeWarrior 8.1Hello, World! (Beginner)The following example writes "Hello, World!" using signals and
slots. First, we create a signal sig, a signal that
takes no arguments and has a void return value. Next, we connect
the hello function object to the signal using the
connect method. Finally, use the signal
sig like a function to call the slots, which in turns
invokes HelloWorld::operator() to print "Hello,
World!".Preferred syntaxPortable syntax
struct HelloWorld
{
void operator()() const
{
std::cout << "Hello, World!" << std::endl;
}
};
// ...
// Signal with no arguments and a void return value
boost::signal<void ()> sig;
// Connect a HelloWorld slot
HelloWorld hello;
sig.connect(hello);
// Call all of the slots
sig();
struct HelloWorld
{
void operator()() const
{
std::cout << "Hello, World!" << std::endl;
}
};
// ...
// Signal with no arguments and a void return value
boost::signal0<void> sig;
// Connect a HelloWorld slot
HelloWorld hello;
sig.connect(hello);
// Call all of the slots
sig();
Calling multiple slotsConnecting multiple slots (Beginner)Calling a single slot from a signal isn't very interesting, so
we can make the Hello, World program more interesting by splitting
the work of printing "Hello, World!" into two completely separate
slots. The first slot will print "Hello" and may look like
this:
struct Hello
{
void operator()() const
{
std::cout << "Hello";
}
};
The second slot will print ", World!" and a newline, to complete
the program. The second slot may look like this:
struct World
{
void operator()() const
{
std::cout << ", World!" << std::endl;
}
};
Like in our previous example, we can create a signal
sig that takes no arguments and has a
void return value. This time, we connect both a
hello and a world slot to the same
signal, and when we call the signal both slots will be called.Preferred syntaxPortable syntaxboost::signal<void ()> sig;
sig.connect(Hello());
sig.connect(World());
sig();
boost::signal0<void> sig;
sig.connect(Hello());
sig.connect(World());
sig();
By default, slots are called in first-in first-out (FIFO) order,
so the output of this program will be as expected:
Hello, World!
Ordering slot call groups (Intermediate)Slots are free to have side effects, and that can mean that some
slots will have to be called before others even if they are not connected in that order. The Boost.Signals
library allows slots to be placed into groups that are ordered in
some way. For our Hello, World program, we want "Hello" to be
printed before ", World!", so we put "Hello" into a group that must
be executed before the group that ", World!" is in. To do this, we
can supply an extra parameter at the beginning of the
connect call that specifies the group. Group values
are, by default, ints, and are ordered by the integer
< relation. Here's how we construct Hello, World:Preferred syntaxPortable syntaxboost::signal<void ()> sig;
sig.connect(1, World());
sig.connect(0, Hello());
sig();
boost::signal0<void> sig;
sig.connect(1, World());
sig.connect(0, Hello());
sig();
This program will correctly print "Hello, World!", because the
Hello object is in group 0, which precedes group 1 where
the World object resides. The group
parameter is, in fact, optional. We omitted it in the first Hello,
World example because it was unnecessary when all of the slots are
independent. So what happens if we mix calls to connect that use the
group parameter and those that don't? The "unnamed" slots (i.e., those
that have been connected without specifying a group name) can be
placed at the front or back of the slot list (by passing
boost::signals::at_front or boost::signals::at_back
as the last parameter to connect, respectively), and defaults to the end of the list. When
a group is specified, the final parameter describes where the slot
will be placed within the group ordering. If we add a new slot
to our example like this:
struct GoodMorning
{
void operator()() const
{
std::cout << "... and good morning!" << std::endl;
}
};
sig.connect(GoodMorning());
... we will get the result we wanted:
Hello, World!
... and good morning!
Passing values to and from slotsSlot Arguments (Beginner)Signals can propagate arguments to each of the slots they call.
For instance, a signal that propagates mouse motion events might
want to pass along the new mouse coordinates and whether the mouse
buttons are pressed.As an example, we'll create a signal that passes two
float arguments to its slots. Then we'll create a few
slots that print the results of various arithmetic operations on
these values.
void print_sum(float x, float y)
{
std::cout << "The sum is " << x+y << std::endl;
}
void print_product(float x, float y)
{
std::cout << "The product is " << x*y << std::endl;
}
void print_difference(float x, float y)
{
std::cout << "The difference is " << x-y << std::endl;
}
void print_quotient(float x, float y)
{
std::cout << "The quotient is " << x/y << std::endl;
}
Preferred syntaxPortable syntaxboost::signal<void (float, float)> sig;
sig.connect(&print_sum);
sig.connect(&print_product);
sig.connect(&print_difference);
sig.connect(&print_quotient);
sig(5, 3);
boost::signal2<void, float, float> sig;
sig.connect(&print_sum);
sig.connect(&print_product);
sig.connect(&print_difference);
sig.connect(&print_quotient);
sig(5, 3);
This program will print out the following:
The sum is 8
The difference is 2
The product is 15
The quotient is 1.66667
So any values that are given to sig when it is
called like a function are passed to each of the slots. We have to
declare the types of these values up front when we create the
signal. The type boost::signal<void (float,
float)> means that the signal has a void
return value and takes two float values. Any slot
connected to sig must therefore be able to take two
float values.Signal Return Values (Advanced)Just as slots can receive arguments, they can also return
values. These values can then be returned back to the caller of the
signal through a combiner. The combiner is a mechanism
that can take the results of calling slots (there many be no
results or a hundred; we don't know until the program runs) and
coalesces them into a single result to be returned to the caller.
The single result is often a simple function of the results of the
slot calls: the result of the last slot call, the maximum value
returned by any slot, or a container of all of the results are some
possibilities.We can modify our previous arithmetic operations example
slightly so that the slots all return the results of computing the
product, quotient, sum, or difference. Then the signal itself can
return a value based on these results to be printed:Preferred syntaxPortable syntax
float product(float x, float y) { return x*y; }
float quotient(float x, float y) { return x/y; }
float sum(float x, float y) { return x+y; }
float difference(float x, float y) { return x-y; }
boost::signal<float (float x, float y)> sig;
sig.connect(&product);
sig.connect("ient);
sig.connect(&sum);
sig.connect(&difference);
std::cout << sig(5, 3) << std::endl;
float product(float x, float y) { return x*y; }
float quotient(float x, float y) { return x/y; }
float sum(float x, float y) { return x+y; }
float difference(float x, float y) { return x-y; }
boost::signal2<float, float, float> sig;
sig.connect(&product);
sig.connect("ient);
sig.connect(&sum);
sig.connect(&difference);
std::cout << sig(5, 3) << std::endl;
This example program will output 2. This is because the
default behavior of a signal that has a return type
(float, the first template argument given to the
boost::signal class template) is to call all slots and
then return the result returned by the last slot called. This
behavior is admittedly silly for this example, because slots have
no side effects and the result is the last slot connect.A more interesting signal result would be the maximum of the
values returned by any slot. To do this, we create a custom
combiner that looks like this:
template<typename T>
struct maximum
{
typedef T result_type;
template<typename InputIterator>
T operator()(InputIterator first, InputIterator last) const
{
// If there are no slots to call, just return the
// default-constructed value
if (first == last)
return T();
T max_value = *first++;
while (first != last) {
if (max_value < *first)
max_value = *first;
++first;
}
return max_value;
}
};
The maximum class template acts as a function
object. Its result type is given by its template parameter, and
this is the type it expects to be computing the maximum based on
(e.g., maximum<float> would find the maximum
float in a sequence of floats). When a
maximum object is invoked, it is given an input
iterator sequence [first, last) that includes the
results of calling all of the slots. maximum uses this
input iterator sequence to calculate the maximum element, and
returns that maximum value.We actually use this new function object type by installing it
as a combiner for our signal. The combiner template argument
follows the signal's calling signature:Preferred syntaxPortable syntaxboost::signal<float (float x, float y),
maximum<float> > sig;
boost::signal2<float, float, float,
maximum<float> > sig;
Now we can connect slots that perform arithmetic functions and
use the signal:
sig.connect("ient);
sig.connect(&product);
sig.connect(&sum);
sig.connect(&difference);
std::cout << sig(5, 3) << std::endl;
The output of this program will be 15, because
regardless of the order in which the slots are connected, the product
of 5 and 3 will be larger than the quotient, sum, or
difference.In other cases we might want to return all of the values
computed by the slots together, in one large data structure. This
is easily done with a different combiner:
template<typename Container>
struct aggregate_values
{
typedef Container result_type;
template<typename InputIterator>
Container operator()(InputIterator first, InputIterator last) const
{
return Container(first, last);
}
};
Again, we can create a signal with this new combiner:
Preferred syntaxPortable syntaxboost::signal<float (float, float),
aggregate_values<std::vector<float> > > sig;
sig.connect("ient);
sig.connect(&product);
sig.connect(&sum);
sig.connect(&difference);
std::vector<float> results = sig(5, 3);
std::copy(results.begin(), results.end(),
std::ostream_iterator<float>(cout, " "));
boost::signal2<float, float, float,
aggregate_values<std::vector<float> > > sig;
sig.connect("ient);
sig.connect(&product);
sig.connect(&sum);
sig.connect(&difference);
std::vector<float> results = sig(5, 3);
std::copy(results.begin(), results.end(),
std::ostream_iterator<float>(cout, " "));
The output of this program will contain 15, 8, 1.6667, and 2. It
is interesting here that
the first template argument for the signal class,
float, is not actually the return type of the signal.
Instead, it is the return type used by the connected slots and will
also be the value_type of the input iterators passed
to the combiner. The combiner itself is a function object and its
result_type member type becomes the return type of the
signal.The input iterators passed to the combiner transform dereference
operations into slot calls. Combiners therefore have the option to
invoke only some slots until some particular criterion is met. For
instance, in a distributed computing system, the combiner may ask
each remote system whether it will handle the request. Only one
remote system needs to handle a particular request, so after a
remote system accepts the work we do not want to ask any other
remote systems to perform the same task. Such a combiner need only
check the value returned when dereferencing the iterator, and
return when the value is acceptable. The following combiner returns
the first non-NULL pointer to a FulfilledRequest data
structure, without asking any later slots to fulfill the
request:
struct DistributeRequest {
typedef FulfilledRequest* result_type;
template<typename InputIterator>
result_type operator()(InputIterator first, InputIterator last) const
{
while (first != last) {
if (result_type fulfilled = *first)
return fulfilled;
++first;
}
return 0;
}
};
Connection ManagementDisconnecting Slots (Beginner)Slots aren't expected to exist indefinately after they are
connected. Often slots are only used to receive a few events and
are then disconnected, and the programmer needs control to decide
when a slot should no longer be connected.The entry point for managing connections explicitly is the
boost::signals::connection class. The
connection class uniquely represents the connection
between a particular signal and a particular slot. The
connected() method checks if the signal and slot are
still connected, and the disconnect() method
disconnects the signal and slot if they are connected before it is
called. Each call to the signal's connect() method
returns a connection object, which can be used to determine if the
connection still exists or to disconnect the signal and slot.
boost::signals::connection c = sig.connect(HelloWorld());
if (c.connected()) {
// c is still connected to the signal
sig(); // Prints "Hello, World!"
}
c.disconnect(); // Disconnect the HelloWorld object
assert(!c.connected()); c isn't connected any more
sig(); // Does nothing: there are no connected slotsScoped connections (Intermediate)The boost::signals::scoped_connection class
references a signal/slot connection that will be disconnected when
the scoped_connection class goes out of scope. This
ability is useful when a connection need only be temporary,
e.g.,
{
boost::signals::scoped_connection c = sig.connect(ShortLived());
sig(); // will call ShortLived function object
}
sig(); // ShortLived function object no longer connected to sigDisconnecting equivalent slots (Intermediate)One can disconnect slots that are equivalent to a given function
object using a form of the
disconnect method, so long as
the type of the function object has an accessible ==
operator. For instance:
Preferred syntaxPortable syntax
void foo();
void bar();
signal<void()> sig;
sig.connect(&foo);
sig.connect(&bar);
// disconnects foo, but not bar
sig.disconnect(&foo);
void foo();
void bar();
signal0<void> sig;
sig.connect(&foo);
sig.connect(&bar);
// disconnects foo, but not bar
sig.disconnect(&foo);
Automatic connection management (Intermediate)Boost.Signals can automatically track the lifetime of objects
involved in signal/slot connections, including automatic
disconnection of slots when objects involved in the slot call are
destroyed. For instance, consider a simple news delivery service,
where clients connect to a news provider that then sends news to
all connected clients as information arrives. The news delivery
service may be constructed like this: Preferred syntaxPortable syntax
class NewsItem { /* ... */ };
boost::signal<void (const NewsItem&)> deliverNews;
class NewsItem { /* ... */ };
boost::signal1<void, const NewsItem&> deliverNews;
Clients that wish to receive news updates need only connect a
function object that can receive news items to the
deliverNews signal. For instance, we may have a
special message area in our application specifically for news,
e.g.,:
struct NewsMessageArea : public MessageArea
{
public:
// ...
void displayNews(const NewsItem& news) const
{
messageText = news.text();
update();
}
};
// ...
NewsMessageArea newsMessageArea = new NewsMessageArea(/* ... */);
// ...
deliverNews.connect(boost::bind(&NewsMessageArea::displayNews,
newsMessageArea, _1));
However, what if the user closes the news message area,
destroying the newsMessageArea object that
deliverNews knows about? Most likely, a segmentation
fault will occur. However, with Boost.Signals one need only make
NewsMessageAreatrackable, and the slot
involving newsMessageArea will be disconnected when
newsMessageArea is destroyed. The
NewsMessageArea class is made trackable by deriving
publicly from the boost::signals::trackable class,
e.g.:
struct NewsMessageArea : public MessageArea, public boost::signals::trackable
{
// ...
};
At this time there is a significant limitation to the use of
trackable objects in making slot connections: function
objects built using Boost.Bind are understood, such that pointers
or references to trackable objects passed to
boost::bind will be found and tracked.Warning: User-defined function objects and function
objects from other libraries (e.g., Boost.Function or Boost.Lambda)
do not implement the required interfaces for trackable
object detection, and will silently ignore any bound trackable
objects. Future versions of the Boost libraries will address
this limitation.When can disconnections occur? (Intermediate)Signal/slot disconnections occur when any of these conditions
occur:The connection is explicitly disconnected via the connection's
disconnect method directly, or indirectly via the
signal's disconnect method or
scoped_connection's destructor.A trackable object bound to the slot is
destroyed.The signal is destroyed.These events can occur at any time without disrupting a signal's
calling sequence. If a signal/slot connection is disconnected at
any time during a signal's calling sequence, the calling sequence
will still continue but will not invoke the disconnected slot.
Additionally, a signal may be destroyed while it is in a calling
sequence, and which case it will complete its slot call sequence
but may not be accessed directly.Signals may be invoked recursively (e.g., a signal A calls a
slot B that invokes signal A...). The disconnection behavior does
not change in the recursive case, except that the slot calling
sequence includes slot calls for all nested invocations of the
signal.Passing slots (Intermediate)Slots in the Boost.Signals library are created from arbitrary
function objects, and therefore have no fixed type. However, it is
commonplace to require that slots be passed through interfaces that
cannot be templates. Slots can be passed via the
slot_type for each particular signal type and any
function object compatible with the signature of the signal can be
passed to a slot_type parameter. For instance:Preferred syntaxPortable syntax
class Button
{
typedef boost::signal<void (int x, int y)> OnClick;
public:
void doOnClick(const OnClick::slot_type& slot);
private:
OnClick onClick;
};
void Button::doOnClick(
const OnClick::slot_type& slot
)
{
onClick.connect(slot);
}
void printCoordinates(long x, long y)
{
std::cout << "(" << x << ", " << y << ")\n";
}
void f(Button& button)
{
button.doOnClick(&printCoordinates);
}
class Button
{
typedef boost::signal2<void,int,int> OnClick;
public:
void doOnClick(const OnClick::slot_type& slot);
private:
OnClick onClick;
};
void Button::doOnClick(
const OnClick::slot_type& slot
)
{
onClick.connect(slot);
}
void printCoordinates(long x, long y)
{
std::cout << "(" << x << ", " << y << ")\n";
}
void f(Button& button)
{
button.doOnClick(&printCoordinates);
}
The doOnClick method is now functionally equivalent
to the connect method of the onClick
signal, but the details of the doOnClick method can be
hidden in an implementation detail file.Linking against the Signals libraryPart of the Boost.Signals library is compiled into a binary
library that must be linked into your application to use Signals. To
build this library, execute the command bjam in
either the top-level Boost directory or in
libs/signals/build. On Unix, the directory
libs/signals/build/bin-stage will then contain
libraries named, e.g., libboost_signals.a that can be
linked in your program with -lboost_signals.On Windows, with Microsoft Visual C++ or Borland C++, the
linking process is nearly automatic. As with the
Regex library, the libraries in
libs\signals\build\bin-stage will have mangled names
and will be automatically be including in the link process. To link
against the Signals library binary dynamically (e.g., using the
Signals DLL), define BOOST_SIGNALS_DYN_LINK when
building your application; to link statically, define
BOOST_SIGNALS_STATIC_LINK. ReferenceHeader <<ulink url="../../boost/signal.hpp">boost/signal.hpp</ulink>>namespace boost {
template<typename R, typename T1, typename T2, ..., typename TN,
typename Combiner = last_value<R>, typename Group = int,
typename GroupCompare = std::less<Group>,
typename SlotFunction = functionN<R, T1, T2, ..., TN> >
class signalN;
template<typename Signature, typename Combiner = last_value<R>,
typename Group = int, typename GroupCompare = std::less<Group>,
typename SlotFunction = functionN<Signature> >
class signal;
namespace signals {
enumconnect_position { at_front, at_back };
}
}Class template signalN3boost::signalNSet of safe multicast callback types.template<typename R, typename T1, typename T2, ..., typename TN,
typename Combiner = last_value<R>, typename Group = int,
typename GroupCompare = std::less<Group>,
typename SlotFunction = functionN<R, T1, T2, ..., TN> >
class signalN : public signals::trackable,
private noncopyable // Exposition only
{
public:
// typestypedeftypename Combiner::result_type result_type;
typedef Combiner combiner_type;
typedef Group group_type;
typedef GroupCompare group_compare_type;
typedef SlotFunction slot_function_type;
typedef slot<SlotFunction> slot_type;
typedefunspecified slot_result_type;
typedefunspecified slot_call_iterator;
typedef T1 argument_type; // If N == 1typedef T1 first_argument_type; // If N == 2typedef T2 second_argument_type; // If N == 2typedef T1 arg1_type;
typedef T2 arg2_type;
.
.
.
typedef TN argN_type;
// static constantsstaticconstint arity = N;
// construct/copy/destruct
signalN(const combiner_type& = combiner_type(),
const group_compare_type& = group_compare_type());
~signalN();
// connection managementsignals::connection
connect(const slot_type&, signals::connect_position = signals::at_back);
signals::connection
connect(const group_type&, const slot_type&,
signals::connect_position = signals::at_back);
void disconnect(const group_type&);
template<typename Slot> void disconnect(const Slot&);
void disconnect_all_slots();
bool empty() const;
std::size_t num_slots() const;
// invocationresult_typeoperator()(arg1_type, arg2_type, ..., argN_type);
result_typeoperator()(arg1_type, arg2_type, ..., argN_type) const;
// combiner accesscombiner_type& combiner();
const combiner_type& combiner() const;
};DescriptionThe class template signalN covers
several related classes signal0, signal1, signal2, etc.,
where the number suffix describes the number of function
parameters the signal and its connected slots will
take. Instead of enumerating all classes, a single pattern
signalN will be described, where N
represents the number of function parameters.<anchor id="signalNconstruct-copy-destruct"/><computeroutput>signalN</computeroutput> construct/copy/destructsignalN(const combiner_type& combiner = combiner_type(),
const group_compare_type& compare = group_compare_type());EffectsInitializes the signal to contain no slots, copies the given combiner into internal storage, and stores the given group comparison function object to compare groups.Postconditionsthis->empty()~signalN();EffectsDisconnects all slots connected to *this.<anchor id="id386837-bb"/><computeroutput>signalN</computeroutput> connection managementsignals::connectionconnect(const slot_type& slot,
signals::connect_position at = signals::at_back);
signals::connectionconnect(const group_type& group, const slot_type& slot,
signals::connect_position at = signals::at_back);EffectsConnects the signal this to the incoming
slot. If the slot is inactive, i.e., any of the trackable
objects bound by the slot call have been destroyed, then the
call to connect is a no-op. If the second version of
connect is invoked, the
slot is associated with the given group. The at
parameter specifies where the slot should be connected:
at_front indicates that the slot will be
connected at the front of the list or group of slots and
at_back indicates that the slot will be
connected at the back of the list or group of
slots.ReturnsA
signals::connection
object that references the newly-created connection between
the signal and the slot; if the slot is inactive, returns a
disconnected connection.ThrowsThis routine meets the strong exception guarantee,
where any exception thrown will cause the slot to not be
connected to the signal.ComplexityConstant time when connecting a slot
without a group name or logarithmic in the number of groups
when connecting to a particular
group.NotesIt is unspecified whether connecting a slot while the
signal is calling will result in the slot being called
immediately.voiddisconnect(const group_type& group);
template<typename Slot> voiddisconnect(const Slot& slot);EffectsIf the parameter is (convertible to) a
group name, any slots in the given group are
disconnected. Otherwise, any slots equal to the given slot
are disconnected.ThrowsWill not throw unless a user destructor or
equality operator == throws. If either throws,
not all slots may be disconnected.ComplexityIf a group is given, O(lg g) + k where
g is the number of groups in the signal and k is the
number of slots in the group. Otherwise, linear in the
number of slots connected to the
signal.voiddisconnect_all_slots();EffectsDisconnects all slots connected to the signal.Postconditionsthis->empty().ThrowsIf disconnecting a slot causes an exception to be
thrown, not all slots may be disconnected.ComplexityLinear in the number of slots known to the
signal.NotesMay be called at any time within the lifetime of the
signal, including during calls to the signal's slots.boolempty() const;Returnstrue if no slots
are connected to the signal, and
false otherwise.ThrowsWill not throw.ComplexityLinear in the number of slots known to the
signal.RationaleSlots can disconnect at any point in time,
including while those same slots are being invoked. It is
therefore possible that the implementation must search
through a list of disconnected slots to determine if any
slots are still connected.std::size_tnum_slots() const;ReturnsThe number of slots connected to the signalThrowsWill not throw.ComplexityLinear in the number of slots known to the
signal.RationaleSlots can disconnect at any point in time,
including while those same slots are being invoked. It is
therefore possible that the implementation must search
through a list of disconnected slots to determine how many
slots are still connected.<anchor id="id426739-bb"/><computeroutput>signalN</computeroutput> invocationresult_typeoperator()(arg1_type a1, arg2_type a2, ... , argN_type aN);
result_typeoperator()(arg1_type a1, arg2_type a2, ... , argN_type aN) const;EffectsInvokes the combiner with a
slot_call_iterator range
[first, last) corresponding to the sequence of calls to the
slots connected to signal
*this. Dereferencing an
iterator in this range causes a slot call with the given set
of parameters (a1, a2, ...,
aN), the result of which is returned from
the iterator dereference operation.ReturnsThe result returned by the combiner.ThrowsIf an exception is thrown by a slot call, or if the
combiner does not dereference any slot past some given slot,
all slots after that slot in the internal list of connected
slots will not be invoked.NotesOnly the slots associated with iterators that are
actually dereferenced will be invoked. Multiple dereferences
of the same iterator will not result in multiple slot
invocations, because the return value of the slot will be
cached.The const version of
the function call operator will invoke the combiner as
const, whereas the
non-const version will
invoke the combiner as
non-const.Calling the function call operator may invoke undefined
behavior if no slots are connected to the signal, depending
on the combiner used. The default combiner is well-defined
for zero slots when the return type is void but is undefined
when the return type is any other type (because there is no
way to synthesize a return value).<anchor id="id270382-bb"/><computeroutput>signalN</computeroutput> combiner accesscombiner_type&combiner();
const combiner_type&combiner() const;ReturnsA reference to the stored combiner.ThrowsWill not throw.Class template signal3boost::signalSafe multicast callback.template<typename Signature, // Function type R (T1, T2, ..., TN)typename Combiner = last_value<R>,
typename Group = int,
typename GroupCompare = std::less<Group>,
typename SlotFunction = functionN<Signature> >
class signal : public signalN<R, T1, T2, ..., TN, Combiner, Group, GroupCompare, SlotFunction>
{
public:
// construct/copy/destruct
signal(const combiner_type& = combiner_type(),
const group_compare_type& = group_compare_type());
};DescriptionClass template signal is a thin
wrapper around the numbered class templates signal0, signal1, etc. It accepts a function
type with N arguments instead of N separate arguments, and
derives from the appropriate signalN
instantiation.All functionality of this class template is in its base
class signalN.<anchor id="signalconstruct-copy-destruct"/><computeroutput>signal</computeroutput> construct/copy/destructsignal(const combiner_type& combiner = combiner_type(),
const group_compare_type& compare = group_compare_type());EffectsInitializes the base class with the given combiner
and comparison objects.Header <<ulink url="../../boost/signals/slot.hpp">boost/signals/slot.hpp</ulink>>namespace boost {
template<typename SlotFunction> class slot;
}Class template slot3boost::slotPass slots as function arguments.template<typename SlotFunction>
class slot {
public:
// construct/copy/destructtemplate<typename Slot> slot(Slot);
};Description<anchor id="slotconstruct-copy-destruct"/><computeroutput>slot</computeroutput> construct/copy/destructtemplate<typename Slot> slot(Slot target);EffectsInvokes
visit_each
(unqualified) to discover pointers and references to
signals::trackable
objects in target.Initializes this to
contain the incoming slot
target, which may be any
function object with which a
SlotFunction can be
constructed.Header <<ulink url="../../boost/signals/trackable.hpp">boost/signals/trackable.hpp</ulink>>namespace boost {
namespace signals {
class trackable;
}
}Class trackable3boost::signals::trackableEnables safe use of multicast callbacks.class trackable {
public:
// construct/copy/destruct
trackable();
trackable(const trackable&);
trackable& operator=(const trackable&);
~trackable();
};DescriptionThe trackable class provides automatic
disconnection of signals and slots when objects bound in
slots (via pointer or reference) are destroyed. The
trackable class may only be used as a public
base class for some other class; when used as such, that
class may be bound to function objects used as part of
slots. The manner in which a trackable object
tracks the set of signal-slot connections it is a part of is
unspecified.The actual use of trackable is contingent
on the presence of appropriate
visit_each overloads for any
type that may contain pointers or references to trackable
objects.<anchor id="trackableconstruct-copy-destruct"/><computeroutput>trackable</computeroutput> construct/copy/destructtrackable();EffectsSets the list of connected slots to empty.ThrowsWill not throw.trackable(const trackable& other);EffectsSets the list of connected slots to empty.ThrowsWill not throw.RationaleSignal-slot connections can only be created via calls to an explicit connect method, and therefore cannot be created here when trackable objects are copied.trackable& operator=(const trackable& other);EffectsSets the list of connected slots to empty.Returns*thisThrowsWill not throw.RationaleSignal-slot connections can only be created via calls to an explicit connect method, and therefore cannot be created here when trackable objects are copied.~trackable();EffectsDisconnects all signal/slot connections that
contain a pointer or reference to this trackable object that
can be found by
visit_each.Header <<ulink url="../../boost/signals/connection.hpp">boost/signals/connection.hpp</ulink>>namespace boost {
namespace signals {
class connection;
void swap(connection&, connection&);
class scoped_connection;
}
}Class connection3boost::signals::connectionQuery/disconnect a signal-slot connection.class connection {
public:
// construct/copy/destruct
connection();
connection(const connection&);
connection& operator=(const connection&);
// connection managementvoid disconnect() const;
bool connected() const;
// modifiersvoid swap(const connection&);
// comparisonsbooloperator==(const connection&) const;
booloperator<(const connection&) const;
};
// specialized algorithmsvoid swap(connection&, connection&);DescriptionThe connection class represents
a connection between a Signal and a Slot. It is a
lightweight object that has the ability to query whether the
signal and slot are currently connected, and to disconnect
the signal and slot. It is always safe to query or
disconnect a connection.<anchor id="connectionconstruct-copy-destruct"/><computeroutput>connection</computeroutput> construct/copy/destructconnection();EffectsSets the currently represented connection to the
NULL connection.Postconditions!this->connected().ThrowsWill not throw.connection(const connection& other);Effectsthis references
the connection referenced by
other.ThrowsWill not throw.connection& operator=(const connection& other);Effectsthis references
the connection referenced by
other.ThrowsWill not throw.<anchor id="id281275-bb"/><computeroutput>connection</computeroutput> connection managementvoiddisconnect() const;EffectsIf
this->connected(),
disconnects the signal and slot referenced by this;
otherwise, this operation is a no-op.Postconditions!this->connected().boolconnected() const;Returnstrue if this
references a non-NULL connection that is still active
(connected), and false
otherwise.ThrowsWill not throw.<anchor id="id243349-bb"/><computeroutput>connection</computeroutput> modifiersvoidswap(const connection& other);EffectsSwaps the connections referenced in
this and
other.ThrowsWill not throw.<anchor id="id404035-bb"/><computeroutput>connection</computeroutput> comparisonsbooloperator==(const connection& other) const;Returnstrue if
this and
other reference the same
connection or both reference the NULL connection, and
false
otherwise.ThrowsWill not throw.booloperator<(const connection& other) const;Returnstrue if the
connection referenced by
this precedes the
connection referenced by
other based on some
unspecified ordering, and
false
otherwise.ThrowsWill not throw.<anchor id="id410784-bb"/><computeroutput>connection</computeroutput> specialized algorithmsvoidswap(connection& x, connection& y);Effectsx.swap(y)ThrowsWill not throw.Class scoped_connection3boost::signals::scoped_connectionLimits a signal-slot connection lifetime to a particular scope.class scoped_connection : private noncopyable // Exposition only
{
public:
// construct/copy/destruct
scoped_connection(const connection&);
~scoped_connection();
// connection managementvoid disconnect() const;
bool connected() const;
};Description<anchor id="scoped_connectionconstruct-copy-destruct"/><computeroutput>scoped_connection</computeroutput> construct/copy/destructscoped_connection(const connection& other);Effectsthis references
the connection referenced by
other.ThrowsWill not throw.~scoped_connection();EffectsIf
this->connected(),
disconnects the signal-slot connection.<anchor id="id445023-bb"/><computeroutput>scoped_connection</computeroutput> connection managementvoiddisconnect() const;EffectsIf
this->connected(),
disconnects the signal and slot referenced by this;
otherwise, this operation is a no-op.Postconditions!this->connected().boolconnected() const;Returnstrue if this
references a non-NULL connection that is still active
(connected), and false
otherwise.ThrowsWill not throw.Header <<ulink url="../../boost/visit_each.hpp">boost/visit_each.hpp</ulink>>namespace boost {
template<typename Visitor, typename T>
void visit_each(const Visitor&, const T&, int);
}Function template visit_each3boost::visit_eachAllow limited exploration of class members.template<typename Visitor, typename T>
void visit_each(const Visitor& visitor, const T& t, int );DescriptionThe visit_each mechanism
allows a visitor to be applied to every subobject in a given
object. It is used by the Signals library to discover
signals::trackable objects within a
function object, but other uses may surface if used
universally (e.g., conservative garbage collection). To fit
within the visit_each framework,
a visit_each overload must be
supplied for each object type. Effectsvisitor(t), and for
every subobject x of
t:
If x is a reference, visit_each(visitor, ref(x), 0)Otherwise, visit_each(visitor, x, 0)NotesThe third parameter is
long for the fallback version
of visit_each and the argument
supplied to this third paramter must always be 0. The third
parameter is an artifact of the widespread lack of proper
function template ordering, and will be removed in the future.Library authors will be expected to add additional
overloads that specialize the T argument for their classes, so
that subobjects can be visited.Calls to visit_each are required to be unqualified, to
enable argument-dependent lookup.Header <<ulink url="../../boost/last_value.hpp">boost/last_value.hpp</ulink>>namespace boost {
template<typename T> class last_value;
template<> class last_value<void>;
}Class template last_value3boost::last_valueEvaluate an InputIterator sequence and return the
last value in the sequence.template<typename T>
class last_value {
public:
// typestypedef T result_type;
// invocationtemplate<typename InputIterator>
result_typeoperator()(InputIterator, InputIterator) const;
};Description<anchor id="id323338-bb"/><computeroutput>last_value</computeroutput> invocationtemplate<typename InputIterator>
result_typeoperator()(InputIterator first, InputIterator last) const;Requiresfirst != lastEffectsDereferences every iterator in the sequence [first, last).ReturnsThe result of dereferencing the iterator last-1.SpecializationsClass last_value<void>Class last_value<void>3boost::last_value<void>Evaluate an InputIterator sequence.class last_value<void> {
public:
// typestypedefunspecified result_type;
// invocationtemplate<typename InputIterator>
result_typeoperator()(InputIterator, InputIterator) const;
};Description<anchor id="id392780-bb"/><computeroutput>last_value</computeroutput> invocationtemplate<typename InputIterator>
result_typeoperator()(InputIterator first, InputIterator last) const;EffectsDereferences every iterator in the sequence [first, last).Frequently Asked QuestionsDon't noncopyable signal semantics mean that a class
with a signal member will be noncopyable as well?No. The compiler will not be able to generate a copy
constructor or copy assignment operator for your class if it
has a signal as a member, but you are free to write your own
copy constructor and/or copy assignment operator. Just don't
try to copy the signal.Is Boost.Signals thread-safe?No. Using Boost.Signals in a multithreaded concept is
very dangerous, and it is very likely that the results will be
less than satisfying. Boost.Signals will support thread safety
in the future.How do I get Boost.Signals to work with Qt?When building with Qt, the Moc keywords
signals and slots are defined using
preprocessor macros, causing programs using Boost.Signals and
Qt together to fail to compile. Although this is a problem
with Qt and not Boost.Signals, a user can use the two systems
together by defining the BOOST_SIGNALS_NAMESPACE
macro to some other identifier (e.g., signalslib)
when building and using the Boost.Signals library. Then the
namespace of the Boost.Signals library will be
boost::BOOST_SIGNALS_NAMESPACE instead of
boost::signals. To retain the original namespace
name in translation units that do not interact with Qt, you
can use a namespace alias:
namespace boost {
namespace signals = BOOST_SIGNALS_NAMESPACE;
}
Design OverviewType Erasure"Type erasure", where static type information is eliminated
by the use of dynamically dispatched interfaces, is used
extensively within the Boost.Signals library to reduce the amount
of code generated by template instantiation. Each signal must
manage a list of slots and their associated connections, along
with a std::map to map from group identifiers to
their associated connections. However, instantiating this map for
every token type, and perhaps within each translation unit (for
some popular template instantiation strategies) increase compile
time overhead and space overhead. To combat this so-called "template bloat", we use
Boost.Function and Boost.Any to store unknown types and
operations. Then, all of the code for handling the list of slots
and the mapping from slot identifiers to connections is factored
into the class signal_base
that deals exclusively with the any and
function objects, hiding the
actual implementations using the well-known pimpl idiom. The
actual signalN class templates
deal only with code that will change depending on the number of
arguments or which is inherently template-dependent (such as
connection).<computeroutput>connection</computeroutput> class The connection class is
central to the behavior of the Boost.Signals library. It is the
only entity within the Boost.Signals system that has knowledge of
all objects that are associated by a given connection. To be
specific, the connection class
itself is merely a thin wrapper over a
shared_ptr to a
basic_connection object.connection objects are
stored by all participants in the Signals system: each
trackable object contains a
list of connection objects
describing all connections it is a part of; similarly, all signals
contain a set of pairs that define a slot. The pairs consist of a
slot function object (generally a Boost.Function object) and a
connection object (that will
disconnect on destruction). Finally, the mapping from slot groups
to slots is based on the key value in a
std::multimap (the stored data
in the std::multimap is the
slot pair).Slot Call Iterator The slot call iterator is conceptually a stack of iterator
adaptors that modify the behavior of the underlying iterator
through the list of slots. The following table describes the type
and behavior of each iterator adaptor required. Note that this is
only a conceptual model: the implementation collapses all these
layers into a single iterator adaptor because several popular
compilers failed to compile the implementation of the conceptual
model.Iterator AdaptorPurposeSlot List IteratorAn iterator through the list of slots
connected to a signal. The value_type of this
iterator will be
std::pair<any,
connection>, where the
any contains an
instance of the slot function type.Filter Iterator AdaptorThis filtering iterator adaptor filters out
slots that have been disconnected, so we never see a
disconnected slot in later stages.Projection Iterator AdaptorThe projection iterator adaptor returns a
reference to the first member of the pair that constitutes
a connected slot (e.g., just the
boost::any object that
holds the slot function).Transform Iterator AdaptorThis transform iterator adaptor performs an
any_cast to
extract a reference to the slot function with the
appropriate slot function type.Transform Iterator AdaptorThis transform iterator adaptor calls the
function object returned by dereferencing the underlying
iterator with the set of arguments given to the signal
itself, and returns the result of that slot
call.Input Caching Iterator AdaptorThis iterator adaptor caches the result of
dereferencing the underlying iterator. Therefore,
dereferencing this iterator multiple times will only
result in the underlying iterator being dereferenced once;
thus, a slot can only be called once but its result can be
used multiple times.Slot Call IteratorIterates over calls to each slot.<computeroutput>visit_each</computeroutput> function template The visit_each
function template is a mechanism for discovering objects that are
stored within another object. Function template
visit_each takes three
arguments: an object to explore, a visitor function object that is
invoked with each subobject, and the int 0. The third parameter is merely a temporary solution to the
widespread lack of proper function template partial ordering. The
primary visit_each
function template specifies this third parameter type to be
long, whereas any user specializations must specify
their third parameter to be of type int. Thus, even
though a broken compiler cannot tell the ordering between, e.g., a
match against a parameter T and a parameter
A<T>, it can determine that the conversion from
the integer 0 to int is better than the conversion to
long. The ordering determined by this conversion thus
achieves partial ordering of the function templates in a limited,
but successful, way. The following example illustrates the use of
this technique:
template<typename> class A {};
template<typename T> void foo(T, long);
template<typename T> void foo(A<T>, int);
A<T> at;
foo(at, 0);
In this example, we assume that our compiler can not tell
that A<T> is a better match than
T, and therefore assume that the function templates
cannot be ordered based on that parameter. Then the conversion
from 0 to int is better than the conversion from 0 to
long, and the second function template is
chosen. Design RationaleChoice of Slot Definitions The definition of a slot differs amongst signals and slots
libraries. Within Boost.Signals, a slot is defined in a very loose
manner: it can be any function object that is callable given
parameters of the types specified by the signal, and whose return
value is convertible to the result type expected by the
signal. However, alternative definitions have associated pros and
cons that were considered prior to the construction of
Boost.Signals.Slots derive from a specific base
class: generally a scheme such as this will require
all user-defined slots to derive from some library-specified
Slot abstract class that defines a virtual
function calling the slot. Adaptors can be used to convert a
definition such as this to a definition similar to that used
by Boost.Signals, but the use of a large number of small
adaptor classes containing virtual functions has been found to
cause an unacceptable increase in the size of executables
(polymorphic class types require more code than
non-polymorphic types). This approach does have the benefit of simplicity of
implementation and user interface, from an object-oriented
perspective.Slots constructed from a set of
primitives: in this scheme the slot can have a
limited set of types (often derived from a common abstract
base class) that are constructed from some library-defined set
of primitives that often include conversions from free
function pointers and member function pointers, and a limited
set of binding capabilities. Such an approach is reasonably
simple and cover most common cases, but it does not allow a
large degree of flexibility in slot construction. Libraries
for function object composition have become quite advanced and
it is out of the scope of a signals and slots library to
encorporate such enhancements. Thus Boost.Signals does not
include argument binding or function object composition
primitives, but instead provides a hook (via the
visit_each
mechanism) that allows existing binder/composition libraries
to provide the necessary information to Signals. Users not satisfied with the slot definition choice may opt
to replace the default slot function type with an alternative that
meets their specific needs.User-level Connection Management Users need to have fine control over the connection of
signals to slots and their eventual disconnection. The approach
taken by Boost.Signals is to return a
connection object that enables
connected/disconnected query, manual disconnection, and an
automatic disconnection on destruction mode. Some other possible
interfaces include:Pass slot to
disconnect: in this interface model, the
disconnection of a slot connected with
sig.connect(slot) is
performed via
sig.disconnect(slot). Internally,
a linear search using slot comparison is performed and the
slot, if found, is removed from the list. Unfortunately,
querying connectedness will generally also end up as
linear-time operations. This model also fails for
implementation reasons when slots become more complex than
simple function pointers, member function pointers and a
limited set of compositions and argument binders: to match the
slot given in the call to
disconnect with an
existing slot we would need to be able to compare arbitrary
function objects, which is not feasible.Pass a token to
disconnect: this approach identifies slots with a
token that is easily comparable (e.g., a string), enabling
slots to be arbitrary function objects. While this approach is
essentially equivalent to the approach taken by Boost.Signals,
it is possibly more error-prone for several reasons:Connections and disconnections must be paired, so
the problem becomes similar to the problems incurred when
pairing new and delete for
dynamic memory allocation. While errors of this sort would
not be catastrophic for a signals and slots
implementation, their detection is generally
nontrivial.Tokens must be unique, otherwise two slots will have
the same name and will be indistinguishable. In
environments where many connections will be made
dynamically, name generation becomes an additional task
for the user. Uniqueness of tokens also results in an
additional failure mode when attempting to connect a slot
using a token that has already been used.More parameterization would be required, because the
token type must be user-defined. Additional
parameterization steepens the learning curver and
overcomplicates a simple interface. This type of interface is supported in Boost.Signals
via the slot grouping mechanism. It augments the
connection object-based
connection management scheme.Combiner Interface The Combiner interface was chosen to mimic a call to an
algorithm in the C++ standard library. It is felt that by viewing
slot call results as merely a sequence of values accessed by input
iterators, the combiner interface would be most natural to a
proficient C++ programmer. Competing interface design generally
required the combiners to be constructed to conform to an
interface that would be customized for (and limited to) the
Signals library. While these interfaces are generally enable more
straighforward implementation of the signals & slots
libraries, the combiners are unfortunately not reusable (either in
other signals & slots libraries or within other generic
algorithms), and the learning curve is steepened slightly to learn
the specific combiner interface. The Signals formulation of combiners is based on the
combiner using the "pull" mode of communication, instead of the
more complex "push" mechanism. With a "pull" mechanism, the
combiner's state can be kept on the stack and in the program
counter, because whenever new data is required (i.e., calling the
next slot to retrieve its return value), there is a simple
interface to retrieve that data immediately and without returning
from the combiner's code. Contrast this with the "push" mechanism,
where the combiner must keep all state in class members because
the combiner's routines will be invoked for each signal
called. Compare, for example, a combiner that returns the maximum
element from calling the slots. If the maximum element ever
exceeds 100, no more slots are to be called.PullPush
struct pull_max {
typedef int result_type;
template<typename InputIterator>
result_type operator()(InputIterator first,
InputIterator last)
{
if (first == last)
throw std::runtime_error("Empty!");
int max_value = *first++;
while(first != last && *first <= 100) {
if (*first > max_value)
max_value = *first;
++first;
}
return max_value;
}
};
struct push_max {
typedef int result_type;
push_max() : max_value(), got_first(false) {}
// returns false when we want to stop
bool operator()(int result) {
if (result > 100)
return false;
if (!got_first) {
got_first = true;
max_value = result;
return true;
}
if (result > max_value)
max_value = result;
return true;
}
int get_value() const
{
if (!got_first)
throw std::runtime_error("Empty!");
return max_value;
}
private:
int max_value;
bool got_first;
};
There are several points to note in these examples. The
"pull" version is a reusable function object that is based on an
input iterator sequence with an integer value_type,
and is very straightforward in design. The "push" model, on the
other hand, relies on an interface specific to the caller and is
not generally reusable. It also requires extra state values to
determine, for instance, if any elements have been
received. Though code quality and ease-of-use is generally
subjective, the "pull" model is clearly shorter and more reusable
and will often be construed as easier to write and understand,
even outside the context of a signals & slots library. The cost of the "pull" combiner interface is paid in the
implementation of the Signals library itself. To correctly handle
slot disconnections during calls (e.g., when the dereference
operator is invoked), one must construct the iterator to skip over
disconnected slots. Additionally, the iterator must carry with it
the set of arguments to pass to each slot (although a reference to
a structure containing those arguments suffices), and must cache
the result of calling the slot so that multiple dereferences don't
result in multiple calls. This apparently requires a large degree
of overhead, though if one considers the entire process of
invoking slots one sees that the overhead is nearly equivalent to
that in the "push" model, but we have inverted the control
structures to make iteration and dereference complex (instead of
making combiner state-finding complex).Connection Interfaces: += operator Boost.Signals supports a connection syntax with the form
sig.connect(slot), but a
more terse syntax sig += slot has been suggested (and
has been used by other signals & slots implementations). There
are several reasons as to why this syntax has been
rejected:It's unnecessary: the
connection syntax supplied by Boost.Signals is no less
powerful that that supplied by the +=
operator. The savings in typing (connect()
vs. +=) is essentially negligible. Furthermore,
one could argue that calling connect() is more
readable than an overload of +=.Ambiguous return type:
there is an ambiguity concerning the return value of the
+= operation: should it be a reference to the
signal itself, to enable sig += slot1 += slot2,
or should it return a
connection for the
newly-created signal/slot connection?Gateway to operators -=,
+: when one has added a connection operator
+=, it seems natural to have a disconnection
operator -=. However, this presents problems when
the library allows arbitrary function objects to implicitly
become slots, because slots are no longer comparable. The second obvious addition when one has
operator+= would be to add a +
operator that supports addition of multiple slots, followed by
assignment to a signal. However, this would require
implementing + such that it can accept any two
function objects, which is technically infeasible.<computeroutput>trackable</computeroutput> rationale The trackable
class is the primary user interface to automatic connection
lifetime management, and its design affects users directly. Two
issues stick out most: the odd copying behavior of
trackable, and the limitation requiring users to
derive from trackable to create types that can
participate in automatic connection management.<computeroutput>trackable</computeroutput> copying behavior The copying behavior of
trackable is essentially
that trackable subobjects
are never copied; instead, the copy operation is merely a
no-op. To understand this, we look at the nature of a
signal-slot connection and note that the connection is based on
the entities that are being connected; when one of the entities
is destroyed, the connection is destroyed. Therefore, when a
trackable subobject is
copied, we cannot copy the connections because the connections
don't refer to the target entity - they refer to the source
entity. This reason is dual to the reason signals are
noncopyable: the slots connected to them are connected to that
particular signal, not the data contained in the signal.Why derivation from <computeroutput>trackable</computeroutput>? For trackable to work
properly, there are two constraints:trackable must
have storage space to keep track of all connections made to
this object.trackable must be
notified when the object is being destructed so that it can
disconnect its connections.Clearly, deriving from
trackable meets these two
guidelines. We have not yet found a superior solution.Comparison with other Signal/Slot implementationslibsigc++libsigc++ is a C++
signals & slots library that originally started as part of
an initiative to wrap the C interfaces to GTK libraries in C++, and has
grown to be a separate library maintained by Karl Nelson. There
are many similarities between libsigc++ and Boost.Signals, and
indeed Boost.Signals was strongly influenced by Karl Nelson and
libsigc++. A cursory inspection of each library will find a
similar syntax for the construction of signals and in the use of
connections and automatic connection lifetime management. There
are some major differences in design that separate these
libraries:Slot definitions:
slots in libsigc++ are created using a set of primitives
defined by the library. These primitives allow binding of
objects (as part of the library), explicit adaptation from
the argument and return types of the signal to the argument
and return types of the slot (libsigc++ is, by default, more
strict about types than Boost.Signals). A discussion of this
approach with a comparison against the approach taken by
Boost.Signals is given in Choice of Slot Definitions.Combiner/Marshaller
interface: the equivalent to Boost.Signals
combiners in libsigc++ are the marshallers. Marshallers are
similar to the "push" interface described in Combiner
Interface, and a proper treatment of the topic is given
there..NET delegatesMicrosoft
has introduced the .NET Framework and an associated set of
languages and language extensions, one of which is the
delegate. Delegates are similar to signals and slots, but they
are more limited than most C++ signals and slots implementations
in that they:Require exact type matches between a delegate and what
it is calling.Only return the result of the last target called, with no option for customization.Must call a method with this already
bound.TestsuiteAcceptance testsTestTypeDescriptionIf failing...dead_slot_test.cpprunEnsure that calling connect with a slot
that has already been disconnected via deletion does not actually
connect to the slot.deletion_test.cpprunTest deletion of slots.ordering_test.cpprunTest slot group ordering.signal_n_test.cpprunBasic test of signal/slot connections and invocation using the
boost::signalN class templates.signal_test.cpprunBasic test of signal/slot connections and invocation using the
boost::signal class template.The boost::signal class template may not
be usable on your compiler. However, the
boost::signalN class templates may still be
usable.trackable_test.cpprunTest automatic lifetime management using
boost::trackable objects.PavolDroba200220032004Pavol DrobaUse, modification and distribution is 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)
Boost String Algorithms LibraryIntroduction
The String Algorithm Library provides a generic implementation of
string-related algorithms which are missing in STL. It is an extension
to the algorithms library of STL and it includes trimming, case conversion,
predicates and find/replace functions. All of them come in different variants
so it is easier to choose the best fit for a particular need.
The implementation is not restricted to work with a particular container
(like std::basic_string), rather it is as generic as
possible. This generalization is not compromising the performance since
algorithms are using container specific features when it means a performance
gain.
Important note: In this documentation we use term string to
designate a sequence of characters stored in an arbitrary container.
A string is not restricted to std::basic_string and
character does not have to be char or wchar_t,
although these are most common candidates.
Consult the design chapter to see precise specification of
supported string types.
The library interface functions and classes are defined in namespace boost::algorithm, and
they are lifted into namespace boost via using declaration.
The documentation is divided into several sections. For a quick start read the
Usage section followed by
Quick Reference.
The Design Topics,
Concepts and Rationale
provide some explanation about the library design and structure an explain how it should be used.
See the Reference for the complete list of provided utilities
and algorithms. Functions and classes in the reference are organized by the headers in which they are defined.
The reference contains links to the detailed description for every entity in the library.
UsageFirst Example
Using the algorithms is straightforward. Let us have a look at the first example:
#include <boost/algorithm/string.hpp>
using namespace std;
using namespace boost;
// ...
string str1(" hello world! ");
to_upper(str1); // str1 == " HELLO WORLD! "
trim(str1); // str1 == "HELLO WORLD!"
string str2=
to_lower_copy(
ireplace_first_copy(
str1,"hello","goodbye")); // str2 == "goodbye world!"
This example converts str1 to upper case and trims spaces from the start and the end
of the string. str2 is then created as a copy of str1 with "hello" replaced with "goodbye".
This example demonstrates several important concepts used in the library:
Container parameters:
Unlike in the STL algorithms, parameters are not specified only in the form
of iterators. The STL convention allows for great flexibility,
but it has several limitations. It is not possible to stack algorithms together,
because a container is passed in two parameters. Therefore it is not possible to use
a return value from another algorithm. It is considerably easier to write
to_lower(str1), than to_lower(str1.begin(), str1.end()).
The magic of collection_traits
provides a uniform way of handling different string types.
If there is a need to pass a pair of iterators,
iterator_range
can be used to package iterators into a structure with a compatible interface.
Copy vs. Mutable:
Many algorithms in the library are performing a transformation of the input.
The transformation can be done in-place, mutating the input sequence, or a copy
of the transformed input can be created, leaving the input intact. None of
these possibilities is superior to the other one and both have different
advantages and disadvantages. For this reason, both are provided with the library.
Algorithm stacking:
Copy versions return a transformed input as a result, thus allow a simple chaining of
transformations within one expression (i.e. one can write trim_copy(to_upper_copy(s))).
Mutable versions have void return, to avoid misuse.
Naming:
Naming follows the conventions from the Standard C++ Library. If there is a
copy and a mutable version of the same algorithm, the mutable version has no suffix
and the copy version has the suffix _copy.
Some algorithms have the prefix i
(e.g. ifind_first()).
This prefix identifies that the algorithm works in a case-insensitive manner.
To use the library, include the boost/algorithm/string.hpp header.
If the regex related functions are needed, include the
boost/algorithm/string_regex.hpp header.
Case conversion
STL has a nice way of converting character case. Unfortunately, it works only
for a single character and we want to convert a string,
string str1("HeLlO WoRld!");
to_upper(str1); // str1=="HELLO WORLD!"
to_upper() and to_lower() convert the case of
characters in a string using a specified locale.
For more information see the reference for boost/algorithm/string/case_conv.hpp.
Predicates and Classification
A part of the library deals with string related predicates. Consider this example:
bool is_executable( string& filename )
{
return
iends_with(filename, ".exe") ||
iends_with(filename, ".com");
}
// ...
string str1("command.com");
cout
<< str1
<< is_executable("command.com")? "is": "is not"
<< "an executable"
<< endl; // prints "command.com is an executable"
//..
char text1[]="hello world!";
cout
<< text1
<< all( text1, is_lower() )? "is": "is not"
<< " written in the lower case"
<< endl; // prints "hello world! is written in the lower case"
The predicates determine whether if a substring is contained in the input string
under various conditions. The conditions are: a string starts with the substring,
ends with the substring,
simply contains the substring or if both strings are equal. See the reference for
boost/algorithm/string/predicate.hpp for more details.
In addition the algorithm all() checks
all elements of a container to satisfy a condition specified by a predicate.
This predicate can be any unary predicate, but the library provides a bunch of
useful string-related predicates and combinators ready for use.
These are located in the boost/algorithm/string/classification.hpp header.
Classification predicates can be combined using logical combinators to form
a more complex expressions. For example: is_from_range('a','z') || is_digit()Trimming
When parsing the input from a user, strings usually have unwanted leading or trailing
characters. To get rid of them, we need trim functions:
string str1=" hello world! ";
string str2=trim_left_copy(str1); // str2 == "hello world! "
string str3=trim_right_copy(str2); // str3 == " hello world!"
trim(str1); // str1 == "hello world!"
string phone="00423333444";
// remove leading 0 from the phone number
trim_left_if(phone,is_any_of("0")); // phone == "423333444"
It is possible to trim the spaces on the right, on the left or on both sides of a string.
And for those cases when there is a need to remove something else than blank space, there
are _if variants. Using these, a user can specify a functor which will
select the space to be removed. It is possible to use classification
predicates like is_digit() mentioned in the previous paragraph.
See the reference for the boost/algorithm/string/trim.hpp.
Find algorithms
The library contains a set of find algorithms. Here is an example:
char text[]="hello dolly!";
iterator_range<char*> result=find_last(text,"ll");
transform( result.begin(), result.end(), result.begin(), bind2nd(plus<char>(), 1) );
// text = "hello dommy!"
to_upper(result); // text == "hello doMMy!"
// iterator_range is convertible to bool
if(find_first(text, "dolly"))
{
cout << "Dolly is there" << endl;
}
We have used find_last() to search the text for "ll".
The result is given in the iterator_range.
This range delimits the
part of the input which satisfies the find criteria. In our example it is the last occurrence of "ll".
As we can see, input of the find_last() algorithm can be also
char[] because this type is supported by
collection_traits.
The following lines transform the result. Notice that
iterator_range has familiar
begin() and end() methods, so it can be used like any other STL container.
Also it is convertible to bool therefore it is easy to use find algorithms for a simple containment checking.
Find algorithms are located in boost/algorithm/string/find.hpp.
Replace Algorithms
Find algorithms can be used for searching for a specific part of string. Replace goes one step
further. After a matching part is found, it is substituted with something else. The substitution is computed
from the original, using some transformation.
string str1="Hello Dolly, Hello World!"
replace_first(str1, "Dolly", "Jane"); // str1 == "Hello Jane, Hello World!"
replace_last(str1, "Hello", "Goodbye"); // str1 == "Hello Jane, Goodbye World!"
erase_all(str1, " "); // str1 == "HelloJane,GoodbyeWorld!"
erase_head(str1, 6); // str1 == "Jane,GoodbyeWorld!"
For the complete list of replace and erase functions see the
reference.
There is a lot of predefined function for common usage, however, the library allows you to
define a custom replace() that suits a specific need. There is a generic find_format()
function which takes two parameters.
The first one is a Finder object, the second one is
a Formatter object.
The Finder object is a functor which performs the searching for the replacement part. The Formatter object
takes the result of the Finder (usually a reference to the found substring) and creates a
substitute for it. Replace algorithm puts these two together and makes the desired substitution.
Check boost/algorithm/string/replace.hpp, boost/algorithm/string/erase.hpp and
boost/algorithm/string/find_format.hpp for reference.
Find Iterator
An extension to find algorithms it the Find Iterator. Instead of searching for just a one part of a string,
the find iterator allows us to iterate over the substrings matching the specified criteria.
This facility is using the Finder to incrementally
search the string.
Dereferencing a find iterator yields an iterator_range
object, that delimits the current match.
There are two iterators provided find_iterator and
split_iterator. The former iterates over substrings that are found using the specified
Finder. The latter iterates over the gaps between these substrings.
string str1("abc-*-ABC-*-aBc");
// Find all 'abc' substrings (ignoring the case)
// Create a find_iterator
typedef find_iterator<string::iterator> string_find_iterator;
for(string_find_iterator It=
make_find_iterator(str1, first_finder("abc", is_iequal()));
It!=string_find_iterator();
++It)
{
cout << copy_iterator_range<std::string>(*It) << endl;
}
// Output will be:
// abc
// ABC
// aBC
typedef split_iterator<string::iterator> string_split_iterator;
for(string_find_iterator It=
make_split_iterator(str1, first_finder("-*-", is_iequal()));
It!=string_find_iterator();
++It)
{
cout << copy_iterator_range<std::string>(*It) << endl;
}
// Output will be:
// abc
// ABC
// aBC
Note that the find iterators have only one template parameter. It is the base iterator type.
The Finder is specified at runtime. This allows us to typedef a find iterator for
common string types and reuse it. Additionally make_*_iterator functions help
to construct a find iterator for a particular collection.
See the reference in boost/algorithm/string/find_iterator.hpp.
Split
Split algorithms are an extension to the find iterator for one common usage scenario.
These algorithms use a find iterator and store all matches into the provided
container. This container must be able to hold copies (e.g. std::string) or
references (e.g. iterator_range) of the extracted substrings.
Two algorithms are provided. find_all() finds all copies
of a string in the input. split() splits the input into parts.
string str1("hello abc-*-ABC-*-aBc goodbye");
typedef vector< iterator_range<string::iterator> > find_vector_type;
find_vector_type FindVec; // #1: Search for separators
ifind_all( FindVec, str1, "abc" ); // FindVec == { [abc],[ABC],[aBc] }
typedef vector< string > split_vector_type;
split_vector_type SplitVec; // #2: Search for tokens
split( SplitVec, str1, is_any_of("-*") ); // SplitVec == { "hello abc","ABC","aBc goodbye" }
[hello] designates an iterator_range delimiting this substring.
First example show how to construct a container to hold references to all extracted
substrings. Algorithm ifind_all() puts into FindVec references
to all substrings that are in case-insensitive manner equal to "abc".
Second example uses split() to split string str1 into parts
separated by characters '-' or '*'. These parts are then put into the SplitVec.
It is possible to specify if adjacent separators are concatenated or not.
More information can be found in the reference: boost/algorithm/string/split.hpp.
Quick ReferenceAlgorithms
Case ConversionAlgorithm nameDescriptionFunctionsto_upperConvert a string to upper caseto_upper_copy()to_upper()to_lowerConvert a string to lower caseto_lower_copy()to_lower()
TrimmingAlgorithm nameDescriptionFunctionstrim_leftRemove leading spaces from a stringtrim_left_copy_if()trim_left_if()trim_left_copy()trim_left()trim_rightRemove trailing spaces from a stringtrim_right_copy_if()trim_right_if()trim_right_copy()trim_right()trimRemove leading and trailing spaces from a stringtrim_copy_if()trim_if()trim_copy()trim()
PredicatesAlgorithm nameDescriptionFunctionsstarts_withCheck if a string is a prefix of the other onestarts_with()istarts_with()ends_withCheck if a string is a suffix of the other oneends_with()iends_with()containsCheck if a string is contained of the other onecontains()icontains()equalsCheck if two strings are equalequals()iequals()allCheck if all elements of a string satisfy the given predicateall()
Find algorithmsAlgorithm nameDescriptionFunctionsfind_firstFind the first occurrence of a string in the inputfind_first()ifind_first()find_lastFind the last occurrence of a string in the inputfind_last()ifind_last()find_nthFind the nth (zero-indexed) occurrence of a string in the inputfind_nth()ifind_nth()find_headRetrieve the head of a stringfind_head()find_tailRetrieve the tail of a stringfind_tail()find_tokenFind first matching token in the stringfind_token()find_regexUse the regular expression to search the stringfind_regex()findGeneric find algorithmfind()
Erase/ReplaceAlgorithm nameDescriptionFunctionsreplace/erase_firstReplace/Erase the first occurrence of a string in the inputreplace_first()replace_first_copy()ireplace_first()ireplace_first_copy()erase_first()erase_first_copy()ierase_first()ierase_first_copy()replace/erase_lastReplace/Erase the last occurrence of a string in the inputreplace_last()replace_last_copy()ireplace_last()ireplace_last_copy()erase_last()erase_last_copy()ierase_last()ierase_last_copy()replace/erase_nthReplace/Erase the nth (zero-indexed) occurrence of a string in the inputreplace_nth()replace_nth_copy()ireplace_nth()ireplace_nth_copy()erase_nth()erase_nth_copy()ierase_nth()ierase_nth_copy()replace/erase_allReplace/Erase the all occurrences of a string in the inputreplace_all()replace_all_copy()ireplace_all()ireplace_all_copy()erase_all()erase_all_copy()ierase_all()ierase_all_copy()replace/erase_headReplace/Erase the head of the inputreplace_head()replace_head_copy()erase_head()erase_head_copy()replace/erase_tailReplace/Erase the tail of the inputreplace_tail()replace_tail_copy()erase_tail()erase_tail_copy()replace/erase_regexReplace/Erase a substring matching the given regular expressionreplace_regex()replace_regex_copy()erase_regex()erase_regex_copy()replace/erase_regex_allReplace/Erase all substrings matching the given regular expressionreplace_all_regex()replace_all_regex_copy()erase_all_regex()erase_all_regex_copy()find_formatGeneric replace algorithmfind_format()find_format_copy()find_format_all()find_format_all_copy()()
SplitAlgorithm nameDescriptionFunctionsfind_allFind/Extract all matching substrings in the inputfind_all()ifind_all()find_all_regex()splitSplit input into partssplit()split_regex()
Finders and Formatters
FindersFinderDescriptionGeneratorsfirst_finderSearch for the first match of the string in an inputfirst_finder()last_finderSearch for the last match of the string in an inputlast_finder()nth_finderSearch for the nth (zero-indexed) match of the string in an inputnth_finder()head_finderRetrieve the head of an inputhead_finder()tail_finderRetrieve the tail of an inputtail_finder()token_finderSearch for a matching token in an inputtoken_finder()range_finderDo no search, always returns the given rangerange_finder()regex_finderSearch for a substring matching the given regexregex_finder()
FormattersFormatterDescriptionGeneratorsconst_formatterConstant formatter. Always return the specified stringconst_formatter()identity_formatterIdentity formatter. Return unmodified input inputidentity_formatter()empty_formatterNull formatter. Always return an empty stringempty_formatter()regex_formatterRegex formatter. Format regex match using the specification in the format stringregex_formatter()
Iterators
Find IteratorsIterator nameDescriptionIterator classfind_iteratorIterates through matching substrings in the inputfind_iteratorsplit_iteratorIterates through gaps between matching substrings in the inputsplit_iterator
Classification
PredicatesPredicate nameDescriptionGeneratoris_classifiedGeneric ctype mask based classificationis_classified()is_spaceRecognize spacesis_space()is_alnumRecognize alphanumeric charactersis_alnum()is_alphaRecognize lettersis_alpha()is_cntrlRecognize control charactersis_cntrl()is_digitRecognize decimal digitsis_digit()is_graphRecognize graphical charactersis_graph()is_lowerRecognize lower case charactersis_lower()is_printRecognize printable charactersis_print()is_punctRecognize punctuation charactersis_punct()is_upperRecognize uppercase charactersis_upper()is_xdigitRecognize hexadecimal digitsis_xdigit()
Design TopicsString Representation
As the name suggest, this library works mainly with strings. However, in the context of this library,
a string is not restricted to any particular implementation (like std::basic_string),
rather it is a concept. This allows the algorithms in this library to be reused for any string type,
that satisfies the given requirements.
Definition: A string is a
collection of characters accessible in sequential
ordered fashion. Character is any value type with "cheap" copying and assignment.
First requirement of string-type is that it must accessible using
collection traits. This facility allows to access
the elements inside the string in a uniform iterator-based fashion.
This requirement is actually less stringent than that of collection concept. It implements
an external collection interface.
This is sufficient for our library
Second requirement defines the way in which the characters are stored in the string. Algorithms in
this library work with an assumption that copying a character is cheaper then allocating extra
storage to cache results. This is a natural assumption for common character types. Algorithms will
work even if this requirement is not satisfied, however at the cost of performance degradation.
In addition some algorithms have additional requirements on the string-type. Particularly, it is required
that an algorithm can create a new string of the given type. In this case, it is required that
the type satisfies the sequence (Std §23.1.1) requirements.
In the reference and also in the code, requirement on the string type is designated by the name of
template argument. CollectionT means that the basic collection requirements must hold.
SequenceT designates extended sequence requirements.
<computeroutput>iterator_range</computeroutput> class
An iterator_range is an encapsulation of a pair of iterators that
delimit a sequence (or, a range). This concept is widely used by
sequence manipulating algorithms. Although being so useful, there no direct support
for it in the standard library (The closest thing is that some algorithms return a pair of iterators).
Instead all STL algorithms have two distinct parameters for beginning and end of a range. This design
is natural for implementation of generic algorithms, but it forbids to work with a range as a single value.
It is possible to encapsulate a range in std::pair<>, but
std::pair<> is an overly generic encapsulation, so it is not best match for a range.
For instance, it does not enforce that begin and end iterators be of the same type.
Naturally the range concept is heavily used also in this library. During the development of
the library, it was discovered, that there is a need for a reasonable encapsulation for it, since
core part of the library deals with substring searching algorithms and any such algorithm
returns a range delimiting the result of the search. std::pair<> was deemed as
unsuitable. Therefore the iterator_range was defined.
The intention of the iterator_range class is to manage a range as a single value and provide
a basic interface for common operations. Its interface is similar to that of a collection.
In addition to begin()
and end() accessors, it has member functions for checking whether the range is empty,
or to determine the size of the range. It also has a set of member typedefs that extract
type information from the encapsulated iterators. As such, the interface is compatible with
the collection traits requirements so
it is possible to use this class as a parameter to many algorithms in this library.
iterator_range will be moved to Boost.Range library in the future
releases. The internal version will be deprecated then.
Collection Traits
Collection traits provide uniform access to different types of
collections .
This functionality allows to write generic algorithms which work with several
different kinds of collections. For this library it means, that, for instance,
many algorithms work with std::string as well as with char[].
This facility implements the
external collection
concept.
The following collection types are supported:
Standard containers
Built-in arrays (like int[])
Null terminated strings (this includes char[],wchar_t[],char*, and wchar_t*)
std::pair<iterator,iterator>
Collection traits support a subset of the container concept (Std §23.1). This subset
can be described as an input container concept, e.g. a container with immutable content.
Its definition can be found in the header boost/algorithm/string/collection_traits.hpp.
In the table C denotes a container and c is an object of C.
Collection TraitsNameStandard collection equivalentDescriptionMaeterlinck
value_type_of<C>::typeC::value_typeType of contained valuesdifference_type_of<C>::typeC::difference_typedifference type of the collectioniterator_of<C>::typeC::iteratoriterator type of the collectionconst_iterator_of<C>::typeC::const_iteratorconst_iterator type of the collectionresult_iterator_of<C>::type
result_iterator type of the collection. This type maps to C::iterator
for mutable collection and C::const_iterator for const collection.
begin(c)c.begin()
Gets the iterator pointing to the start of the collection.
end(c)c.end()
Gets the iterator pointing to the end of the collection.
size(c)c.size()
Gets the size of the collection.
empty(c)c.empty()
Checks if the collection is empty.
The collection traits are only a temporary part of this library. They will be replaced in the future
releases by Boost.Range library. Use of the internal implementation will be deprecated then.
Sequence Traits
The major difference between std::list and std::vector is not in the interfaces
they provide, but rather in the inner details of the class and the way how it performs
various operations. The problem is that it is not possible to infer this difference from the
definitions of classes without some special mechanism.
However, some algorithms can run significantly faster with the knowledge of the properties
of a particular container.
Sequence traits allow one to specify additional properties of a sequence container (see Std.§32.2).
These properties are then used by algorithms to select optimized handling for some operations.
The sequence traits are declared in the header
boost/algorithm/string/sequence_traits.hpp.
In the table C denotes a container and c is an object of C.
Sequence TraitsTraitDescriptionhas_native_replace<C>::valueSpecifies that the sequence has std::string like replace methodhas_stable_iterators<C>::value
Specifies that the sequence has stable iterators. It means,
that operations like insert/erase/replace
do not invalidate iterators.
has_const_time_insert<C>::value
Specifies that the insert method of the sequence has
constant time complexity.
has_const_time_erase<C>::value
Specifies that the erase method of the sequence has constant time complexity
Current implementation contains specializations for std::list<T> and
std::basic_string<T> from the standard library and SGI's std::rope<T> and std::slist<T>.
Find Algorithms
Find algorithms have similar functionality to std::search() algorithm. They provide a different
interface which is more suitable for common string operations.
Instead of returning just the start of matching subsequence they return a range which is necessary
when the length of the matching subsequence is not known beforehand.
This feature also allows a partitioning of the input sequence into three
parts: a prefix, a substring and a suffix.
Another difference is an addition of various searching methods besides find_first, including find_regex.
It the library, find algorithms are implemented in terms of
Finders. Finders are used also by other facilities
(replace,split).
For convenience, there are also function wrappers for these finders to simplify find operations.
Currently the library contains only naive implementation of find algorithms with complexity
O(n * m) where n is the size of the input sequence and m is the size of the search sequence.
There are algorithms with complexity O(n), but for smaller sequence a constant overhead is
rather big. For small m << n (m by magnitude smaller than n) the current implementation
provides acceptable efficiency.
Even the C++ standard defines the required complexity for search algorithm as O(n * m).
It is possible that a future version of library will also contain algorithms with linear
complexity as an option
Replace Algorithms
The implementation of replace algorithms follows the layered structure of the library. The
lower layer implements generic substitution of a range in the input sequence.
This layer takes a Finder object and a
Formatter object as an input. These two
functors define what to replace and what to replace it with. The upper layer functions
are just wrapping calls to the lower layer. Finders are shared with the find and split facility.
As usual, the implementation of the lower layer is designed to work with a generic sequence while
taking advantage of specific features if possible
(by using Sequence traits)
Find Iterators & Split Algorithms
Find iterators are a logical extension of the find facility.
Instead of searching for one match, the whole input can be iteratively searched for multiple matches.
The result of the search is then used to partition the input. It depends on the algorithms which parts
are returned as the result. They can be the matching parts (find_iterator) of the parts in
between (split_iterator).
In addition the split algorithms like find_all() and split()
can simplify the common operations. They use a find iterator to search the whole input and copy the
matches they found into the supplied container.
Exception Safety
The library requires that all operations on types used as template
or function arguments provide the basic exception-safety guarantee.
In turn, all functions and algorithms in this library, except where stated
otherwise, will provide the basic exception-safety guarantee.
In other words:
The library maintains its invariants and does not leak resources in
the face of exceptions. Some library operations give stronger
guarantees, which are documented on an individual basis.
Some functions can provide the strong exception-safety guarantee.
That means that following statements are true:
If an exception is thrown, there are no effects other than those
of the function
If an exception is thrown other than by the function, there are no effects
This guarantee can be provided under the condition that the operations
on the types used for arguments for these functions either
provide the strong exception guarantee or do not alter the global state .
In the reference, under the term strong exception-safety guarantee, we mean the
guarantee as defined above.
For more information about the exception safety topics, follow this
linkConceptsDefinitions
NotationFA type that is a model of FinderFmtA type that is a model of FormatterIter
Iterator Type
fObject of type FfmtObject of type Fmti,jObjects of type Iter
Finder Concept
Finder is a functor which searches for an arbitrary part of a container.
The result of the search is given as an iterator_range
delimiting the selected part.
Valid ExpressionsExpressionReturn TypeEffectsf(i,j)Convertible to iterator_range<Iter>Perform the search on the interval [i,j) and returns the result of the search
Various algorithms need to perform a search in a container and a Finder is a generalization of such
search operations that allows algorithms to abstract from searching. For instance, generic replace
algorithms can replace any part of the input, and the Finder is used to select the desired one.
Note, that it is only required that the finder works with a particular iterator type. However,
a Finder operation can be defined as a template, allowing the Finder to work with any iterator.
Examples
Finder implemented as a class. This Finder always returns the whole input as a match. operator()
is templated, so that the finder can be used on any iterator type.
struct simple_finder
{
template<typename ForwardIteratorT>
boost::iterator_range<ForwardIterator> operator()(
ForwardIteratorT Begin,
ForwardIteratorT End )
{
return boost::make_range( Begin, End );
}
};
Function Finder. Finder can be any function object. That is, any ordinary function with the
required signature can be used as well. However, such a function can be used only for
a specific iterator type.
boost::iterator_range<std::string> simple_finder(
std::string::const_iterator Begin,
std::string::const_iterator End )
{
return boost::make_range( Begin, End );
}
Formatter concept
Formatters are used by replace algorithms.
They are used in close combination with finders.
A formatter is a functor, which takes a result from a Finder operation and transforms it in a specific way.
The operation of the formatter can use additional information provided by a specific finder,
for example regex_formatter() uses the match information from
regex_finder() to format the result of formatter operation.
Valid ExpressionsExpressionReturn TypeEffectsfmt(f(i,j))A container type, accessible using container traitsFormats the result of the finder operation
Similarly to finders, formatters generalize format operations. When a finder is used to
select a part of the input, formatter takes this selection and performs some formating
on it. Algorithms can abstract from formating using a formatter.
Examples
Formatter implemented as a class. This Formatter does not perform any formating and
returns the match, repackaged. operator()
is templated, so that the Formatter can be used on any Finder type.
struct simple_formatter
{
template<typename FindResultT>
std::string operator()( const FindResultT& Match )
{
std::string Temp( Match.begin(), Match.end() );
return Temp;
}
};
Function Formatter. Similarly to Finder, Formatter can be any function object.
However, as a function, it can be used only with a specific Finder type.
std::string simple_formatter( boost::iterator_range<std::string::const_iterator>& Match )
{
std::string Temp( Match.begin(), Match.end() );
return Temp;
}
ReferenceHeader <<ulink url="../../boost/algorithm/string/case_conv.hpp">boost/algorithm/string/case_conv.hpp</ulink>>Defines sequence case-conversion algorithms. Algorithms convert each element in the input sequence to the desired case using provided locales.namespace boost {
namespace algorithm {
template<typename OutputIteratorT, typename CollectionT>
OutputIteratorT
to_lower_copy(OutputIteratorT, const CollectionT &,
const std::locale & = std::locale());
template<typename SequenceT>
SequenceT to_lower_copy(const SequenceT &,
const std::locale & = std::locale());
template<typename MutableCollectionT>
void to_lower(MutableCollectionT &, const std::locale & = std::locale());
template<typename OutputIteratorT, typename CollectionT>
OutputIteratorT
to_upper_copy(OutputIteratorT, const CollectionT &,
const std::locale & = std::locale());
template<typename SequenceT>
SequenceT to_upper_copy(const SequenceT &,
const std::locale & = std::locale());
template<typename MutableCollectionT>
void to_upper(MutableCollectionT &, const std::locale & = std::locale());
}
}Function to_lower_copy3boost::algorithm::to_lower_copyConvert to lower case. template<typename OutputIteratorT, typename CollectionT>
OutputIteratorT
to_lower_copy(OutputIteratorT Output, const CollectionT & Input,
const std::locale & Loc = std::locale());
template<typename SequenceT>
SequenceT to_lower_copy(const SequenceT & Input,
const std::locale & Loc = std::locale());DescriptionEach element of the input sequence is converted to lower case. The result is a copy of the input converted to lower case. It is returned as a sequence or copied to the output iterator.ParametersInputAn input collection LocA locale used for conversion OutputAn output iterator to which the result will be copied ReturnsAn output iterator pointing just after the last inserted character or a copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template to_lower3boost::algorithm::to_lowerConvert to lower case. template<typename MutableCollectionT>
void to_lower(MutableCollectionT & Input,
const std::locale & Loc = std::locale());DescriptionEach element of the input sequence is converted to lower case. The input sequence is modified in-place.ParametersInputA collection Loca locale used for conversion Function to_upper_copy3boost::algorithm::to_upper_copyConvert to upper case. template<typename OutputIteratorT, typename CollectionT>
OutputIteratorT
to_upper_copy(OutputIteratorT Output, const CollectionT & Input,
const std::locale & Loc = std::locale());
template<typename SequenceT>
SequenceT to_upper_copy(const SequenceT & Input,
const std::locale & Loc = std::locale());DescriptionEach element of the input sequence is converted to upper case. The result is a copy of the input converted to upper case. It is returned as a sequence or copied to the output iteratorParametersInputAn input collection LocA locale used for conversion OutputAn output iterator to which the result will be copied ReturnsAn output iterator pointing just after the last inserted character or a copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template to_upper3boost::algorithm::to_upperConvert to upper case. template<typename MutableCollectionT>
void to_upper(MutableCollectionT & Input,
const std::locale & Loc = std::locale());DescriptionEach element of the input sequence is converted to upper case. The input sequence is modified in-place.ParametersInputAn input collection Loca locale used for conversion Header <<ulink url="../../boost/algorithm/string/classification.hpp">boost/algorithm/string/classification.hpp</ulink>>Classification predicates are included in the library to give some more convenience when using algorithms like trim() and all() . They wrap functionality of STL classification functions ( e.g. std::isspace() ) into generic functors.namespace boost {
namespace algorithm {
unspecified is_classified(std::ctype_base::mask,
const std::locale & = std::locale());
unspecified is_space(const std::locale & = std::locale());
unspecified is_alnum(const std::locale & = std::locale());
unspecified is_alpha(const std::locale & = std::locale());
unspecified is_cntrl(const std::locale & = std::locale());
unspecified is_digit(const std::locale & = std::locale());
unspecified is_graph(const std::locale & = std::locale());
unspecified is_lower(const std::locale & = std::locale());
unspecified is_print(const std::locale & = std::locale());
unspecified is_punct(const std::locale & = std::locale());
unspecified is_upper(const std::locale & = std::locale());
unspecified is_xdigit(const std::locale & = std::locale());
template<typename ContainerT> unspecified is_any_of(const ContainerT &);
template<typename CharT> unspecified is_from_range(CharT, CharT);
template<typename Pred1T, typename Pred2T>
unspecifiedoperator&&(const predicate_facade< Pred1T > &,
const predicate_facade< Pred2T > &);
template<typename Pred1T, typename Pred2T>
unspecifiedoperator||(const predicate_facade< Pred1T > &,
const predicate_facade< Pred2T > &);
template<typename PredT>
unspecifiedoperator!(const predicate_facade< PredT > &);
}
}Function is_classified3boost::algorithm::is_classifiedis_classified predicate unspecified is_classified(std::ctype_base::mask Type,
const std::locale & Loc = std::locale());DescriptionConstruct the is_classified predicate. This predicate holds if the input is of specified std::ctype category.ParametersLocA locale used for classification TypeA std::ctype category ReturnsAn instance of the is_classified predicate Function is_space3boost::algorithm::is_spaceis_space predicate unspecified is_space(const std::locale & Loc = std::locale());DescriptionConstruct the is_classified predicate for the ctype_base::space category.ParametersLocA locale used for classification ReturnsAn instance of the is_classified predicate Function is_alnum3boost::algorithm::is_alnumis_alnum predicate unspecified is_alnum(const std::locale & Loc = std::locale());DescriptionConstruct the is_classified predicate for the ctype_base::alnum category.ParametersLocA locale used for classification ReturnsAn instance of the is_classified predicate Function is_alpha3boost::algorithm::is_alphais_alpha predicate unspecified is_alpha(const std::locale & Loc = std::locale());DescriptionConstruct the is_classified predicate for the ctype_base::alpha category.ParametersLocA locale used for classification ReturnsAn instance of the is_classified predicate Function is_cntrl3boost::algorithm::is_cntrlis_cntrl predicate unspecified is_cntrl(const std::locale & Loc = std::locale());DescriptionConstruct the is_classified predicate for the ctype_base::cntrl category.ParametersLocA locale used for classification ReturnsAn instance of the is_classified predicate Function is_digit3boost::algorithm::is_digitis_digit predicate unspecified is_digit(const std::locale & Loc = std::locale());DescriptionConstruct the is_classified predicate for the ctype_base::digit category.ParametersLocA locale used for classification ReturnsAn instance of the is_classified predicate Function is_graph3boost::algorithm::is_graphis_graph predicate unspecified is_graph(const std::locale & Loc = std::locale());DescriptionConstruct the is_classified predicate for the ctype_base::graph category.ParametersLocA locale used for classification ReturnsAn instance of the is_classified predicate Function is_lower3boost::algorithm::is_loweris_lower predicate unspecified is_lower(const std::locale & Loc = std::locale());DescriptionConstruct the is_classified predicate for the ctype_base::lower category.ParametersLocA locale used for classification ReturnsAn instance of is_classified predicate Function is_print3boost::algorithm::is_printis_print predicate unspecified is_print(const std::locale & Loc = std::locale());DescriptionConstruct the is_classified predicate for the ctype_base::print category.ParametersLocA locale used for classification ReturnsAn instance of the is_classified predicate Function is_punct3boost::algorithm::is_punctis_punct predicate unspecified is_punct(const std::locale & Loc = std::locale());DescriptionConstruct the is_classified predicate for the ctype_base::punct category.ParametersLocA locale used for classification ReturnsAn instance of the is_classified predicate Function is_upper3boost::algorithm::is_upperis_upper predicate unspecified is_upper(const std::locale & Loc = std::locale());DescriptionConstruct the is_classified predicate for the ctype_base::upper category.ParametersLocA locale used for classification ReturnsAn instance of the is_classified predicate Function is_xdigit3boost::algorithm::is_xdigitis_xdigit predicate unspecified is_xdigit(const std::locale & Loc = std::locale());DescriptionConstruct the is_classified predicate for the ctype_base::xdigit category.ParametersLocA locale used for classification ReturnsAn instance of the is_classified predicate Function template is_any_of3boost::algorithm::is_any_ofis_any_of predicate template<typename ContainerT> unspecified is_any_of(const ContainerT & Set);DescriptionConstruct the is_any_of predicate. The predicate holds if the input is included in the specified set of characters.ParametersSetA set of characters to be recognized ReturnsAn instance of the is_any_of predicate Function template is_from_range3boost::algorithm::is_from_rangeis_from_range predicate template<typename CharT> unspecified is_from_range(CharT From, CharT To);DescriptionConstruct the is_from_range predicate. The predicate holds if the input is included in the specified range. (i.e. From <= Ch <= To )ParametersFromThe start of the range ToThe end of the range ReturnsAn instance of the is_from_range predicate Function template operator&&3boost::algorithm::operator&&predicate 'and' composition predicate template<typename Pred1T, typename Pred2T>
unspecifiedoperator&&(const predicate_facade< Pred1T > & Pred1,
const predicate_facade< Pred2T > & Pred2);DescriptionConstruct the class_and predicate. This predicate can be used to logically combine two classification predicates. class_and holds, if both predicates return true.ParametersPred1The first predicate Pred2The second predicate ReturnsAn instance of the class_and predicate Function template operator||3boost::algorithm::operator||predicate 'or' composition predicate template<typename Pred1T, typename Pred2T>
unspecifiedoperator||(const predicate_facade< Pred1T > & Pred1,
const predicate_facade< Pred2T > & Pred2);DescriptionConstruct the class_or predicate. This predicate can be used to logically combine two classification predicates. class_or holds, if one of the predicates return true.ParametersPred1The first predicate Pred2The second predicate ReturnsAn instance of the class_or predicate Function template operator!3boost::algorithm::operator!predicate negation operator template<typename PredT>
unspecifiedoperator!(const predicate_facade< PredT > & Pred);DescriptionConstruct the class_not predicate. This predicate represents a negation. class_or holds if of the predicates return false.ParametersPredThe predicate to be negated ReturnsAn instance of the class_not predicate Header <<ulink url="../../boost/algorithm/string/collection_traits.hpp">boost/algorithm/string/collection_traits.hpp</ulink>>Defines collection_traits class and related free-standing functions. This facility is used to unify the access to different types of collections. It allows the algorithms in the library to work with STL collections, c-style array, null-terminated c-strings (and more) using the same interface.namespace boost {
namespace algorithm {
template<typename T> struct collection_traits;
template<typename C> struct value_type_of;
template<typename C> struct difference_type_of;
template<typename C> struct iterator_of;
template<typename C> struct const_iterator_of;
template<typename C> struct result_iterator_of;
template<typename C> collection_traits< C >::size_type size(const C &);
template<typename C> bool empty(const C &);
template<typename C> collection_traits< C >::iterator begin(C &);
template<typename C>
collection_traits< C >::const_iterator begin(const C &);
template<typename C> collection_traits< C >::iterator end(C &);
template<typename C> collection_traits< C >::const_iterator end(const C &);
}
}Struct template collection_traits3boost::algorithm::collection_traitscollection_traits class template<typename T>
struct collection_traits {
// typestypedef container_helper_type function_type; // Function type. typedef container_helper_type::value_type value_type; // Value type. typedef container_helper_type::size_type size_type; // Size type. typedef container_helper_type::iterator iterator; // Iterator type. typedef container_helper_type::const_iterator const_iterator; // Const iterator type. typedef container_helper_type::result_iterator result_iterator; // Result iterator type ( iterator of const_iterator, depending on the constness of the container ). typedef container_helper_type::difference_type difference_type; // Difference type.
};DescriptionCollection traits provide uniform access to different types of collections. This functionality allows to write generic algorithms which work with several different kinds of collections.Currently following collection types are supported:containers with STL compatible container interface ( see ContainerConcept ) ( i.e. std::vector<> , std::list<> , std::string<> ... )c-style array ( char [10], int [15] ... )null-terminated c-strings ( char* , wchar_T* )std::pair of iterators ( i.e std::pair<vector<int>::iterator ,vector<int>::iterator> )Collection traits provide an external collection interface operations. All are accessible using free-standing functions.The following operations are supported:size()empty()begin()end()Container traits have somewhat limited functionality on compilers not supporting partial template specialization and partial template ordering. Struct template value_type_of3boost::algorithm::value_type_ofContainer value_type trait. template<typename C>
struct value_type_of {
// typestypedef collection_traits< C >::value_type type;
};DescriptionExtract the type of elements contained in a container Struct template difference_type_of3boost::algorithm::difference_type_ofContainer difference trait. template<typename C>
struct difference_type_of {
// typestypedef collection_traits< C >::difference_type type;
};DescriptionExtract the container's difference type Struct template iterator_of3boost::algorithm::iterator_ofContainer iterator trait. template<typename C>
struct iterator_of {
// typestypedef collection_traits< C >::iterator type;
};DescriptionExtract the container's iterator type Struct template const_iterator_of3boost::algorithm::const_iterator_ofContainer const_iterator trait. template<typename C>
struct const_iterator_of {
// typestypedef collection_traits< C >::const_iterator type;
};DescriptionExtract the container's const_iterator type Struct template result_iterator_of3boost::algorithm::result_iterator_ofContainer result_iterator. template<typename C>
struct result_iterator_of {
// typestypedef collection_traits< C >::result_iterator type;
};DescriptionExtract the container's result_iterator type. This type maps to C::iterator for mutable container and C::const_iterator for const containers. Function template size3boost::algorithm::sizeFree-standing size() function. template<typename C> collection_traits< C >::size_type size(const C & c);DescriptionGet the size of the container. Uses collection_traits. Function template empty3boost::algorithm::emptyFree-standing empty() function. template<typename C> bool empty(const C & c);DescriptionCheck whether the container is empty. Uses container traits. Function begin3boost::algorithm::beginFree-standing begin() function. template<typename C> collection_traits< C >::iterator begin(C & c);
template<typename C> collection_traits< C >::const_iterator begin(const C & c);DescriptionGet the begin iterator of the container. Uses collection_traits. Function end3boost::algorithm::endFree-standing end() function. template<typename C> collection_traits< C >::iterator end(C & c);
template<typename C> collection_traits< C >::const_iterator end(const C & c);DescriptionGet the begin iterator of the container. Uses collection_traits. Header <<ulink url="../../boost/algorithm/string/compare.hpp">boost/algorithm/string/compare.hpp</ulink>>Defines element comparison predicates. Many algorithms in this library can take an additional argument with a predicate used to compare elements. This makes it possible, for instance, to have case insensitive versions of the algorithms.namespace boost {
namespace algorithm {
struct is_equal;
struct is_iequal;
}
}Struct is_equal3boost::algorithm::is_equalis_equal functor struct is_equal {
// public member functionstemplate<typename T1, typename T2>
booloperator()(const T1 &, const T2 &) const;
};DescriptionStandard STL equal_to only handle comparison between arguments of the same type. This is a less restrictive version which wraps operator ==. <anchor id="id222448-bb"/><computeroutput>is_equal</computeroutput> public member functionstemplate<typename T1, typename T2>
booloperator()(const T1 & Arg1, const T2 & Arg2) const;Compare two operands for equality Struct is_iequal3boost::algorithm::is_iequalcase insensitive version of is_equal struct is_iequal {
// construct/copy/destruct
is_iequal(const std::locale & = std::locale());
// public member functionstemplate<typename T1, typename T2>
booloperator()(const T1 &, const T2 &) const;
};DescriptionCase insensitive comparison predicate. Comparison is done using specified locales. <anchor id="is_iequalconstruct-copy-destruct"/><computeroutput>is_iequal</computeroutput> construct/copy/destructis_iequal(const std::locale & Loc = std::locale());ParametersLoclocales used for comparison <anchor id="id304317-bb"/><computeroutput>is_iequal</computeroutput> public member functionstemplate<typename T1, typename T2>
booloperator()(const T1 & Arg1, const T2 & Arg2) const;Compare two operands. Case is ignored. Header <<ulink url="../../boost/algorithm/string/concept.hpp">boost/algorithm/string/concept.hpp</ulink>>Defines concepts used in string_algo librarynamespace boost {
namespace algorithm {
template<typename FinderT, typename IteratorT> struct FinderConcept;
template<typename FormatterT, typename FinderT, typename IteratorT>
struct FormatterConcept;
}
}Struct template FinderConcept3boost::algorithm::FinderConceptFinder concept. template<typename FinderT, typename IteratorT>
struct FinderConcept {
// public member functionsvoid constraints() ;
};DescriptionDefines the Finder concept. Finder is a functor which selects an arbitrary part of a string. Search is performed on the range specified by starting and ending iterators.Result of the find operation must be convertible to iterator_range. <anchor id="id432848-bb"/><computeroutput>FinderConcept</computeroutput> public member functionsvoidconstraints() ;Struct template FormatterConcept3boost::algorithm::FormatterConceptFormatter concept. template<typename FormatterT, typename FinderT, typename IteratorT>
struct FormatterConcept {
// public member functionsvoid constraints() ;
};DescriptionDefines the Formatter concept. Formatter is a functor, which takes a result from a finder operation and transforms it in a specific way.Result must be a container supported by container_traits, or a reference to it. <anchor id="id459750-bb"/><computeroutput>FormatterConcept</computeroutput> public member functionsvoidconstraints() ;Header <<ulink url="../../boost/algorithm/string/constants.hpp">boost/algorithm/string/constants.hpp</ulink>>namespace boost {
namespace algorithm {
enum token_compress_mode_type;
}
}Type token_compress_mode_type3boost::algorithm::token_compress_mode_typeToken compression mode. enum token_compress_mode_type { token_compress_on, token_compress_off };Header <<ulink url="../../boost/algorithm/string/erase.hpp">boost/algorithm/string/erase.hpp</ulink>>Defines various erase algorithms. Each algorithm removes part(s) of the input according to a searching criteria.namespace boost {
namespace algorithm {
template<typename OutputIteratorT, typename CollectionT>
OutputIteratorT
erase_range_copy(OutputIteratorT, const CollectionT &,
const iterator_range< typename const_iterator_of< CollectionT >::type > &);
template<typename SequenceT>
SequenceT erase_range_copy(const SequenceT &,
const iterator_range< typename const_iterator_of< SequenceT >::type > &);
template<typename SequenceT>
void erase_range(SequenceT &,
const iterator_range< typename iterator_of< SequenceT >::type > &);
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
erase_first_copy(OutputIteratorT, const Collection1T &,
const Collection2T &);
template<typename SequenceT, typename CollectionT>
SequenceT erase_first_copy(const SequenceT &, const CollectionT &);
template<typename SequenceT, typename CollectionT>
void erase_first(SequenceT &, const CollectionT &);
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
ierase_first_copy(OutputIteratorT, const Collection1T &,
const Collection2T &,
const std::locale & = std::locale());
template<typename SequenceT, typename CollectionT>
SequenceT ierase_first_copy(const SequenceT &, const CollectionT &,
const std::locale & = std::locale());
template<typename SequenceT, typename CollectionT>
void ierase_first(SequenceT &, const CollectionT &,
const std::locale & = std::locale());
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
erase_last_copy(OutputIteratorT, const Collection1T &,
const Collection2T &);
template<typename SequenceT, typename CollectionT>
SequenceT erase_last_copy(const SequenceT &, const CollectionT &);
template<typename SequenceT, typename CollectionT>
void erase_last(SequenceT &, const CollectionT &);
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
ierase_last_copy(OutputIteratorT, const Collection1T &,
const Collection2T &,
const std::locale & = std::locale());
template<typename SequenceT, typename CollectionT>
SequenceT ierase_last_copy(const SequenceT &, const CollectionT &,
const std::locale & = std::locale());
template<typename SequenceT, typename CollectionT>
void ierase_last(SequenceT &, const CollectionT &,
const std::locale & = std::locale());
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
erase_nth_copy(OutputIteratorT, const Collection1T &,
const Collection2T &, unsignedint);
template<typename SequenceT, typename CollectionT>
SequenceT erase_nth_copy(const SequenceT &, const CollectionT &,
unsignedint);
template<typename SequenceT, typename CollectionT>
void erase_nth(SequenceT &, const CollectionT &, unsignedint);
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
ierase_nth_copy(OutputIteratorT, const Collection1T &,
const Collection2T &, unsignedint,
const std::locale & = std::locale());
template<typename SequenceT, typename CollectionT>
SequenceT ierase_nth_copy(const SequenceT &, const CollectionT &,
unsignedint,
const std::locale & = std::locale());
template<typename SequenceT, typename CollectionT>
void ierase_nth(SequenceT &, const CollectionT &, unsignedint,
const std::locale & = std::locale());
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
erase_all_copy(OutputIteratorT, const Collection1T &,
const Collection2T &);
template<typename SequenceT, typename CollectionT>
SequenceT erase_all_copy(const SequenceT &, const CollectionT &);
template<typename SequenceT, typename CollectionT>
void erase_all(SequenceT &, const CollectionT &);
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
ierase_all_copy(OutputIteratorT, const Collection1T &,
const Collection2T &,
const std::locale & = std::locale());
template<typename SequenceT, typename CollectionT>
SequenceT ierase_all_copy(const SequenceT &, const CollectionT &,
const std::locale & = std::locale());
template<typename SequenceT, typename CollectionT>
void ierase_all(SequenceT &, const CollectionT &,
const std::locale & = std::locale());
template<typename OutputIteratorT, typename CollectionT>
OutputIteratorT
erase_head_copy(OutputIteratorT, const CollectionT &, unsignedint);
template<typename SequenceT>
SequenceT erase_head_copy(const SequenceT &, unsignedint);
template<typename SequenceT> void erase_head(SequenceT &, unsignedint);
template<typename OutputIteratorT, typename CollectionT>
OutputIteratorT
erase_tail_copy(OutputIteratorT, const CollectionT &, unsignedint);
template<typename SequenceT>
SequenceT erase_tail_copy(const SequenceT &, unsignedint);
template<typename SequenceT> void erase_tail(SequenceT &, unsignedint);
}
}Function erase_range_copy3boost::algorithm::erase_range_copyErase range algorithm. template<typename OutputIteratorT, typename CollectionT>
OutputIteratorT
erase_range_copy(OutputIteratorT Output, const CollectionT & Input,
const iterator_range< typename const_iterator_of< CollectionT >::type > & SearchRange);
template<typename SequenceT>
SequenceT erase_range_copy(const SequenceT & Input,
const iterator_range< typename const_iterator_of< SequenceT >::type > & SearchRange);DescriptionRemove the given range from the input. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersInputAn input sequence OutputAn output iterator to which the result will be copied SearchRangeA range in the input to be removed ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template erase_range3boost::algorithm::erase_rangeErase range algorithm. template<typename SequenceT>
void erase_range(SequenceT & Input,
const iterator_range< typename iterator_of< SequenceT >::type > & SearchRange);DescriptionRemove the given range from the input. The input sequence is modified in-place.ParametersInputAn input sequence SearchRangeA range in the input to be removed Function erase_first_copy3boost::algorithm::erase_first_copyErase first algorithm. template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
erase_first_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search);
template<typename SequenceT, typename CollectionT>
SequenceT erase_first_copy(const SequenceT & Input,
const CollectionT & Search);DescriptionRemove the first occurence of the substring from the input. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersInputAn input string OutputAn output iterator to which the result will be copied SearchA substring to be searched for ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template erase_first3boost::algorithm::erase_firstErase first algorithm. template<typename SequenceT, typename CollectionT>
void erase_first(SequenceT & Input, const CollectionT & Search);DescriptionRemove the first occurence of the substring from the input. The input sequence is modified in-place.ParametersInputAn input string SearchA substring to be searched for. Function ierase_first_copy3boost::algorithm::ierase_first_copyErase first algorithm ( case insensitive ). template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
ierase_first_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search,
const std::locale & Loc = std::locale());
template<typename SequenceT, typename CollectionT>
SequenceT ierase_first_copy(const SequenceT & Input,
const CollectionT & Search,
const std::locale & Loc = std::locale());DescriptionRemove the first occurence of the substring from the input. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator. Searching is case insensitive.ParametersInputAn input string LocA locale used for case insensitive comparison OutputAn output iterator to which the result will be copied SearchA substring to be searched for ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template ierase_first3boost::algorithm::ierase_firstErase first algorithm ( case insensitive ). template<typename SequenceT, typename CollectionT>
void ierase_first(SequenceT & Input, const CollectionT & Search,
const std::locale & Loc = std::locale());DescriptionRemove the first occurence of the substring from the input. The input sequence is modified in-place. Searching is case insensitive.ParametersInputAn input string LocA locale used for case insensitive comparison SearchA substring to be searched for Function erase_last_copy3boost::algorithm::erase_last_copyErase last algorithm. template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
erase_last_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search);
template<typename SequenceT, typename CollectionT>
SequenceT erase_last_copy(const SequenceT & Input,
const CollectionT & Search);DescriptionRemove the last occurence of the substring from the input. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersInputAn input string OutputAn output iterator to which the result will be copied SearchA substring to be searched for. ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template erase_last3boost::algorithm::erase_lastErase last algorithm. template<typename SequenceT, typename CollectionT>
void erase_last(SequenceT & Input, const CollectionT & Search);DescriptionRemove the last occurence of the substring from the input. The input sequence is modified in-place.ParametersInputAn input string SearchA substring to be searched for Function ierase_last_copy3boost::algorithm::ierase_last_copyErase last algorithm ( case insensitive ). template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
ierase_last_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search,
const std::locale & Loc = std::locale());
template<typename SequenceT, typename CollectionT>
SequenceT ierase_last_copy(const SequenceT & Input,
const CollectionT & Search,
const std::locale & Loc = std::locale());DescriptionRemove the last occurence of the substring from the input. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator. Searching is case insensitive.ParametersInputAn input string LocA locale used for case insensitive comparison OutputAn output iterator to which the result will be copied SearchA substring to be searched for ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template ierase_last3boost::algorithm::ierase_lastErase last algorithm ( case insensitive ). template<typename SequenceT, typename CollectionT>
void ierase_last(SequenceT & Input, const CollectionT & Search,
const std::locale & Loc = std::locale());DescriptionRemove the last occurence of the substring from the input. The input sequence is modified in-place. Searching is case insensitive.ParametersInputAn input string LocA locale used for case insensitive comparison SearchA substring to be searched for Function erase_nth_copy3boost::algorithm::erase_nth_copyErase nth algorithm. template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
erase_nth_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search, unsignedint Nth);
template<typename SequenceT, typename CollectionT>
SequenceT erase_nth_copy(const SequenceT & Input,
const CollectionT & Search, unsignedint Nth);DescriptionRemove the Nth occurence of the substring in the input. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersInputAn input string NthAn index of the match to be replaced. The index is 0-based. OutputAn output iterator to which the result will be copied SearchA substring to be searched for ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template erase_nth3boost::algorithm::erase_nthErase nth algorithm. template<typename SequenceT, typename CollectionT>
void erase_nth(SequenceT & Input, const CollectionT & Search,
unsignedint Nth);DescriptionRemove the Nth occurence of the substring in the input. The input sequence is modified in-place.ParametersInputAn input string NthAn index of the match to be replaced. The index is 0-based. SearchA substring to be searched for. Function ierase_nth_copy3boost::algorithm::ierase_nth_copyErase nth algorithm ( case insensitive ). template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
ierase_nth_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search, unsignedint Nth,
const std::locale & Loc = std::locale());
template<typename SequenceT, typename CollectionT>
SequenceT ierase_nth_copy(const SequenceT & Input,
const CollectionT & Search, unsignedint Nth,
const std::locale & Loc = std::locale());DescriptionRemove the Nth occurence of the substring in the input. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator. Searching is case insensitive.ParametersInputAn input string LocA locale used for case insensitive comparison NthAn index of the match to be replaced. The index is 0-based. OutputAn output iterator to which the result will be copied SearchA substring to be searched for. ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template ierase_nth3boost::algorithm::ierase_nthErase nth algorithm. template<typename SequenceT, typename CollectionT>
void ierase_nth(SequenceT & Input, const CollectionT & Search,
unsignedint Nth, const std::locale & Loc = std::locale());DescriptionRemove the Nth occurence of the substring in the input. The input sequence is modified in-place. Searching is case insensitive.ParametersInputAn input string LocA locale used for case insensitive comparison NthAn index of the match to be replaced. The index is 0-based. SearchA substring to be searched for. Function erase_all_copy3boost::algorithm::erase_all_copyErase all algorithm. template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
erase_all_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search);
template<typename SequenceT, typename CollectionT>
SequenceT erase_all_copy(const SequenceT & Input,
const CollectionT & Search);DescriptionRemove all the occurrences of the string from the input. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersInputAn input sequence OutputAn output iterator to which the result will be copied SearchA substring to be searched for. ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template erase_all3boost::algorithm::erase_allErase all algorithm. template<typename SequenceT, typename CollectionT>
void erase_all(SequenceT & Input, const CollectionT & Search);DescriptionRemove all the occurrences of the string from the input. The input sequence is modified in-place.ParametersInputAn input string SearchA substring to be searched for. Function ierase_all_copy3boost::algorithm::ierase_all_copyErase all algorithm ( case insensitive ). template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
ierase_all_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search,
const std::locale & Loc = std::locale());
template<typename SequenceT, typename CollectionT>
SequenceT ierase_all_copy(const SequenceT & Input,
const CollectionT & Search,
const std::locale & Loc = std::locale());DescriptionRemove all the occurrences of the string from the input. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator. Searching is case insensitive.ParametersInputAn input string LocA locale used for case insensitive comparison OutputAn output iterator to which the result will be copied SearchA substring to be searched for ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template ierase_all3boost::algorithm::ierase_allErase all algorithm ( case insensitive ). template<typename SequenceT, typename CollectionT>
void ierase_all(SequenceT & Input, const CollectionT & Search,
const std::locale & Loc = std::locale());DescriptionRemove all the occurrences of the string from the input. The input sequence is modified in-place. Searching is case insensitive.ParametersInputAn input string LocA locale used for case insensitive comparison SearchA substring to be searched for. Function erase_head_copy3boost::algorithm::erase_head_copyErase head algorithm. template<typename OutputIteratorT, typename CollectionT>
OutputIteratorT
erase_head_copy(OutputIteratorT Output, const CollectionT & Input,
unsignedint N);
template<typename SequenceT>
SequenceT erase_head_copy(const SequenceT & Input, unsignedint N);DescriptionRemove the head from the input. The head is a prefix of a seqence of given size. If the sequence is shorter then required, the whole string is considered to be the head. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersInputAn input string NLength of the head OutputAn output iterator to which the result will be copied ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template erase_head3boost::algorithm::erase_headErase head algorithm. template<typename SequenceT>
void erase_head(SequenceT & Input, unsignedint N);DescriptionRemove the head from the input. The head is a prefix of a seqence of given size. If the sequence is shorter then required, the whole string is considered to be the head. The input sequence is modified in-place.ParametersInputAn input string NLength of the head Function erase_tail_copy3boost::algorithm::erase_tail_copyErase tail algorithm. template<typename OutputIteratorT, typename CollectionT>
OutputIteratorT
erase_tail_copy(OutputIteratorT Output, const CollectionT & Input,
unsignedint N);
template<typename SequenceT>
SequenceT erase_tail_copy(const SequenceT & Input, unsignedint N);DescriptionRemove the tail from the input. The tail is a suffix of a seqence of given size. If the sequence is shorter then required, the whole string is considered to be the tail. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersInputAn input string NLength of the head OutputAn output iterator to which the result will be copied ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template erase_tail3boost::algorithm::erase_tailErase tail algorithm. template<typename SequenceT>
void erase_tail(SequenceT & Input, unsignedint N);DescriptionRemove the tail from the input. The tail is a suffix of a seqence of given size. If the sequence is shorter then required, the whole string is considered to be the tail. The input sequence is modified in-place.ParametersInputAn input string NLength of the head Header <<ulink url="../../boost/algorithm/string/find.hpp">boost/algorithm/string/find.hpp</ulink>>Defines a set of find algorithms. The algorithms are searching for a substring of the input. The result is given as an iterator_range delimiting the substring.namespace boost {
namespace algorithm {
template<typename CollectionT, typename FinderT>
iterator_range< typename result_iterator_of< CollectionT >::type >
find(CollectionT &, FinderT);
template<typename Collection1T, typename Collection2T>
iterator_range< typename result_iterator_of< Collection1T >::type >
find_first(Collection1T &, const Collection2T &);
template<typename Collection1T, typename Collection2T>
iterator_range< typename result_iterator_of< Collection1T >::type >
ifind_first(Collection1T &, const Collection2T &,
const std::locale & = std::locale());
template<typename Collection1T, typename Collection2T>
iterator_range< typename result_iterator_of< Collection1T >::type >
find_last(Collection1T &, const Collection2T &);
template<typename Collection1T, typename Collection2T>
iterator_range< typename result_iterator_of< Collection1T >::type >
ifind_last(Collection1T &, const Collection2T &,
const std::locale & = std::locale());
template<typename Collection1T, typename Collection2T>
iterator_range< typename result_iterator_of< Collection1T >::type >
find_nth(Collection1T &, const Collection2T &, unsignedint);
template<typename Collection1T, typename Collection2T>
iterator_range< typename result_iterator_of< Collection1T >::type >
ifind_nth(Collection1T &, const Collection2T &, unsignedint,
const std::locale & = std::locale());
template<typename CollectionT>
iterator_range< typename result_iterator_of< CollectionT >::type >
find_head(CollectionT &, unsignedint);
template<typename CollectionT>
iterator_range< typename result_iterator_of< CollectionT >::type >
find_tail(CollectionT &, unsignedint);
template<typename CollectionT, typename PredicateT>
iterator_range< typename result_iterator_of< CollectionT >::type >
find_token(CollectionT &, PredicateT,
token_compress_mode_type = token_compress_off);
}
}Function template find3boost::algorithm::findGeneric find algorithm. template<typename CollectionT, typename FinderT>
iterator_range< typename result_iterator_of< CollectionT >::type >
find(CollectionT & Input, FinderT Finder);DescriptionSearch the input using the given finder.ParametersFinderFinder object used for searching. InputA string which will be searched. ReturnsAn iterator_range delimiting the match. Returned iterator is either CollectionT::iterator or CollectionT::const_iterator , depending on the constness of the input parameter. Function template find_first3boost::algorithm::find_firstFind first algorithm. template<typename Collection1T, typename Collection2T>
iterator_range< typename result_iterator_of< Collection1T >::type >
find_first(Collection1T & Input, const Collection2T & Search);DescriptionSearch for the first occurence of the substring in the input.ParametersInputA string which will be searched. SearchA substring to be searched for. ReturnsAn iterator_range delimiting the match. Returned iterator is either CollectionT::iterator or CollectionT::const_iterator , depending on the constness of the input parameter.NotesThis function provides the strong exception-safety guarantee Function template ifind_first3boost::algorithm::ifind_firstFind first algorithm ( case insensitive ). template<typename Collection1T, typename Collection2T>
iterator_range< typename result_iterator_of< Collection1T >::type >
ifind_first(Collection1T & Input, const Collection2T & Search,
const std::locale & Loc = std::locale());DescriptionSearch for the first occurence of the substring in the input. Searching is case insensitive.ParametersInputA string which will be searched. LocA locale used for case insensitive comparison SearchA substring to be searched for. ReturnsAn iterator_range delimiting the match. Returned iterator is either Collection1T::iterator or Collection1T::const_iterator , depending on the constness of the input parameter.NotesThis function provides the strong exception-safety guarantee Function template find_last3boost::algorithm::find_lastFind last algorithm. template<typename Collection1T, typename Collection2T>
iterator_range< typename result_iterator_of< Collection1T >::type >
find_last(Collection1T & Input, const Collection2T & Search);DescriptionSearch for the last occurence of the substring in the input.ParametersInputA string which will be searched. SearchA substring to be searched for. ReturnsAn iterator_range delimiting the match. Returned iterator is either Collection1T::iterator or Collection1T::const_iterator , depending on the constness of the input parameter.NotesThis function provides the strong exception-safety guarantee Function template ifind_last3boost::algorithm::ifind_lastFind last algorithm ( case insensitive ). template<typename Collection1T, typename Collection2T>
iterator_range< typename result_iterator_of< Collection1T >::type >
ifind_last(Collection1T & Input, const Collection2T & Search,
const std::locale & Loc = std::locale());DescriptionSearch for the last match a string in the input. Searching is case insensitive.ParametersInputA string which will be searched. LocA locale used for case insensitive comparison SearchA substring to be searched for. ReturnsAn iterator_range delimiting the match. Returned iterator is either Collection1T::iterator or Collection1T::const_iterator , depending on the constness of the input parameter.NotesThis function provides the strong exception-safety guarantee Function template find_nth3boost::algorithm::find_nthFind n-th algorithm. template<typename Collection1T, typename Collection2T>
iterator_range< typename result_iterator_of< Collection1T >::type >
find_nth(Collection1T & Input, const Collection2T & Search,
unsignedint Nth);DescriptionSearch for the n-th (zero-indexed) occurence of the substring in the input.ParametersInputA string which will be searched. NthAn index (zero-indexed) of the match to be found. SearchA substring to be searched for. ReturnsAn iterator_range delimiting the match. Returned iterator is either Collection1T::iterator or Collection1T::const_iterator , depending on the constness of the input parameter. Function template ifind_nth3boost::algorithm::ifind_nthFind n-th algorithm ( case insensitive ). template<typename Collection1T, typename Collection2T>
iterator_range< typename result_iterator_of< Collection1T >::type >
ifind_nth(Collection1T & Input, const Collection2T & Search,
unsignedint Nth, const std::locale & Loc = std::locale());DescriptionSearch for the n-th (zero-indexed) occurence of the substring in the input. Searching is case insensitive.ParametersInputA string which will be searched. LocA locale used for case insensitive comparison NthAn index (zero-indexed) of the match to be found. SearchA substring to be searched for. ReturnsAn iterator_range delimiting the match. Returned iterator is either Collection1T::iterator or Collection1T::const_iterator , depending on the constness of the input parameter.NotesThis function provides the strong exception-safety guarantee Function template find_head3boost::algorithm::find_headFind head algorithm. template<typename CollectionT>
iterator_range< typename result_iterator_of< CollectionT >::type >
find_head(CollectionT & Input, unsignedint N);DescriptionGet the head of the input. Head is a prefix of the string of the given size. If the input is shorter then required, whole input if considered to be the head.ParametersInputAn input string NLength of the head ReturnsAn iterator_range delimiting the match. Returned iterator is either Collection1T::iterator or Collection1T::const_iterator , depending on the constness of the input parameter.NotesThis function provides the strong exception-safety guarantee Function template find_tail3boost::algorithm::find_tailFind tail algorithm. template<typename CollectionT>
iterator_range< typename result_iterator_of< CollectionT >::type >
find_tail(CollectionT & Input, unsignedint N);DescriptionGet the head of the input. Head is a suffix of the string of the given size. If the input is shorter then required, whole input if considered to be the tail.ParametersInputAn input string NLength of the tail ReturnsAn iterator_range delimiting the match. Returned iterator is either CollectionT::iterator or CollectionT::const_iterator , depending on the constness of the input parameter.NotesThis function provides the strong exception-safety guarantee Function template find_token3boost::algorithm::find_tokenFind token algorithm. template<typename CollectionT, typename PredicateT>
iterator_range< typename result_iterator_of< CollectionT >::type >
find_token(CollectionT & Input, PredicateT Pred,
token_compress_mode_type eCompress = token_compress_off);DescriptionLook for a given token in the string. Token is a character that matches the given predicate. If the "token compress mode" is enabled, adjacent tokens are considered to be one match.ParametersInputA input string. PredAn unary predicate to identify a token eCompressEnable/Disable compressing of adjacent tokens ReturnsAn iterator_range delimiting the match. Returned iterator is either CollectionT::iterator or CollectionT::const_iterator , depending on the constness of the input parameter.NotesThis function provides the strong exception-safety guarantee Header <<ulink url="../../boost/algorithm/string/find_format.hpp">boost/algorithm/string/find_format.hpp</ulink>>Defines generic replace algorithms. Each algorithm replaces part(s) of the input. The part to be replaced is looked up using a Finder object. Result of finding is then used by a Formatter object to generate the replacement.namespace boost {
namespace algorithm {
template<typename OutputIteratorT, typename CollectionT, typename FinderT,
typename FormatterT>
OutputIteratorT
find_format_copy(OutputIteratorT, const CollectionT &, FinderT,
FormatterT);
template<typename SequenceT, typename FinderT, typename FormatterT>
SequenceT find_format_copy(const SequenceT &, FinderT, FormatterT);
template<typename SequenceT, typename FinderT, typename FormatterT>
void find_format(SequenceT &, FinderT, FormatterT);
template<typename OutputIteratorT, typename CollectionT, typename FinderT,
typename FormatterT>
OutputIteratorT
find_format_all_copy(OutputIteratorT, const CollectionT &, FinderT,
FormatterT);
template<typename SequenceT, typename FinderT, typename FormatterT>
SequenceT find_format_all_copy(const SequenceT &, FinderT, FormatterT);
template<typename SequenceT, typename FinderT, typename FormatterT>
void find_format_all(SequenceT &, FinderT, FormatterT);
template<typename CharT, typename RegexTraitsT, typename RegexAllocatorT>
unspecified regex_finder(const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
match_flag_type = match_default);
template<typename CharT, typename TraitsT, typename AllocT>
unspecified regex_formatter(const std::basic_string< CharT, TraitsT, AllocT > &,
match_flag_type = format_default);
}
}Function find_format_copy3boost::algorithm::find_format_copyGeneric replace algorithm. template<typename OutputIteratorT, typename CollectionT, typename FinderT,
typename FormatterT>
OutputIteratorT
find_format_copy(OutputIteratorT Output, const CollectionT & Input,
FinderT Finder, FormatterT Formatter);
template<typename SequenceT, typename FinderT, typename FormatterT>
SequenceT find_format_copy(const SequenceT & Input, FinderT Finder,
FormatterT Formatter);DescriptionUse the Finder to search for a substring. Use the Formatter to format this substring and replace it in the input. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersFinderA Finder object used to search for a match to be replaced FormatterA Formatter object used to format a match InputAn input sequence OutputAn output iterator to which the result will be copied ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template find_format3boost::algorithm::find_formatGeneric replace algorithm. template<typename SequenceT, typename FinderT, typename FormatterT>
void find_format(SequenceT & Input, FinderT Finder, FormatterT Formatter);DescriptionUse the Finder to search for a substring. Use the Formatter to format this substring and replace it in the input. The input is modified in-place.ParametersFinderA Finder object used to search for a match to be replaced FormatterA Formatter object used to format a match InputAn input sequence Function find_format_all_copy3boost::algorithm::find_format_all_copyGeneric replace all algorithm. template<typename OutputIteratorT, typename CollectionT, typename FinderT,
typename FormatterT>
OutputIteratorT
find_format_all_copy(OutputIteratorT Output, const CollectionT & Input,
FinderT Finder, FormatterT Formatter);
template<typename SequenceT, typename FinderT, typename FormatterT>
SequenceT find_format_all_copy(const SequenceT & Input, FinderT Finder,
FormatterT Formatter);DescriptionUse the Finder to search for a substring. Use the Formatter to format this substring and replace it in the input. Repeat this for all matching substrings. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersFinderA Finder object used to search for a match to be replaced FormatterA Formatter object used to format a match InputAn input sequence OutputAn output iterator to which the result will be copied ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template find_format_all3boost::algorithm::find_format_allGeneric replace all algorithm. template<typename SequenceT, typename FinderT, typename FormatterT>
void find_format_all(SequenceT & Input, FinderT Finder,
FormatterT Formatter);DescriptionUse the Finder to search for a substring. Use the Formatter to format this substring and replace it in the input. Repeat this for all matching substrings.The input is modified in-place.ParametersFinderA Finder object used to search for a match to be replaced FormatterA Formatter object used to format a match InputAn input sequence Function template regex_finder3boost::algorithm::regex_finder"Regex" finder template<typename CharT, typename RegexTraitsT, typename RegexAllocatorT>
unspecified regex_finder(const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
match_flag_type MatchFlags = match_default);DescriptionConstruct the regex_finder . Finder uses the regex engine to search for a match. Result is given in regex_search_result . This is an extension of the iterator_range. In addition it containes match results from the regex_search algorithm.ParametersMatchFlagsRegex search options RxA regular expression ReturnsAn instance of the regex_finder object Function template regex_formatter3boost::algorithm::regex_formatterRegex formatter. template<typename CharT, typename TraitsT, typename AllocT>
unspecified regex_formatter(const std::basic_string< CharT, TraitsT, AllocT > & Format,
match_flag_type Flags = format_default);DescriptionConstruct the regex_formatter . Regex formatter uses the regex engine to format a match found by the regex_finder . This formatted it designed to closely cooperate with regex_finder .ParametersFlagsFormat flags FormatRegex format definition ReturnsAn instance of the regex_formatter functor Header <<ulink url="../../boost/algorithm/string/find_iterator.hpp">boost/algorithm/string/find_iterator.hpp</ulink>>Defines find iterator classes. Find iterator repeatly applies a Finder to the specified input string to search for matches. Dereferencing the iterator yields the current match or a range between the last and the current match depending on the iterator used.namespace boost {
namespace algorithm {
template<typename IteratorT> class find_iterator;
template<typename IteratorT> class split_iterator;
template<typename CollectionT, typename FinderT>
find_iterator< typename result_iterator_of< CollectionT >::type >
make_find_iterator(CollectionT &, FinderT);
template<typename CollectionT, typename FinderT>
split_iterator< typename result_iterator_of< CollectionT >::type >
make_split_iterator(CollectionT &, FinderT);
}
}Class template find_iterator3boost::algorithm::find_iteratorfind_iterator template<typename IteratorT>
class find_iterator {
public:
// construct/copy/destruct
find_iterator();
find_iterator(const find_iterator &);
template<typename FinderT> find_iterator(IteratorT, IteratorT, FinderT);
template<typename FinderT, typename CollectionT>
find_iterator(CollectionT &, FinderT);
// public member functionsbool eof() const;
// private member functionsconst match_type & dereference() const;
void increment() ;
bool equal(const find_iterator &) const;
};DescriptionFind iterator encapsulates a Finder and allows for incremental searching in a string. Each increment moves the iterator to the next match.Find iterator is a readable forward traversal iterator.Dereferencing the iterator yields an iterator_range delimiting the current match. <anchor id="find_iteratorconstruct-copy-destruct"/><computeroutput>find_iterator</computeroutput> construct/copy/destructfind_iterator();Construct null iterator. All null iterators are equal.Postconditionseof()==true find_iterator(const find_iterator & Other);Construct a copy of the find_iterator template<typename FinderT>
find_iterator(IteratorT Begin, IteratorT End, FinderT Finder);Construct new find_iterator for a given finder and a range. template<typename FinderT, typename CollectionT>
find_iterator(CollectionT & Col, FinderT Finder);Construct new find_iterator for a given finder and a collection. <anchor id="id227806-bb"/><computeroutput>find_iterator</computeroutput> public member functionsbooleof() const;Check the eof condition. Eof condition means that there is nothing more to be searched i.e. find_iterator is after the last match. <anchor id="id426473-bb"/><computeroutput>find_iterator</computeroutput> private member functionsconst match_type &dereference() const;voidincrement() ;boolequal(const find_iterator & Other) const;Class template split_iterator3boost::algorithm::split_iteratorsplit_iterator template<typename IteratorT>
class split_iterator {
public:
// construct/copy/destruct
split_iterator();
split_iterator(const split_iterator &);
template<typename FinderT> split_iterator(IteratorT, IteratorT, FinderT);
template<typename FinderT, typename CollectionT>
split_iterator(CollectionT &, FinderT);
// public member functionsbool eof() const;
// private member functionsconst match_type & dereference() const;
void increment() ;
bool equal(const split_iterator &) const;
};DescriptionSplit iterator encapsulates a Finder and allows for incremental searching in a string. Unlike the find iterator, split iterator iterates through gaps between matches.Find iterator is a readable forward traversal iterator.Dereferencing the iterator yields an iterator_range delimiting the current match. <anchor id="split_iteratorconstruct-copy-destruct"/><computeroutput>split_iterator</computeroutput> construct/copy/destructsplit_iterator();Construct null iterator. All null iterators are equal.Postconditionseof()==true split_iterator(const split_iterator & Other);Construct a copy of the split_iterator template<typename FinderT>
split_iterator(IteratorT Begin, IteratorT End, FinderT Finder);Construct new split_iterator for a given finder and a range. template<typename FinderT, typename CollectionT>
split_iterator(CollectionT & Col, FinderT Finder);Construct new split_iterator for a given finder and a collection. <anchor id="id427406-bb"/><computeroutput>split_iterator</computeroutput> public member functionsbooleof() const;Check the eof condition. Eof condition means that there is nothing more to be searched i.e. find_iterator is after the last match. <anchor id="id421533-bb"/><computeroutput>split_iterator</computeroutput> private member functionsconst match_type &dereference() const;voidincrement() ;boolequal(const split_iterator & Other) const;Function template make_find_iterator3boost::algorithm::make_find_iteratorfind iterator construction helper template<typename CollectionT, typename FinderT>
find_iterator< typename result_iterator_of< CollectionT >::type >
make_find_iterator(CollectionT & Collection, FinderT Finder);DescriptionConstruct a find iterator to iterate through the specified string Function template make_split_iterator3boost::algorithm::make_split_iteratorsplit iterator construction helper template<typename CollectionT, typename FinderT>
split_iterator< typename result_iterator_of< CollectionT >::type >
make_split_iterator(CollectionT & Collection, FinderT Finder);DescriptionConstruct a split iterator to iterate through the specified collection Header <<ulink url="../../boost/algorithm/string/finder.hpp">boost/algorithm/string/finder.hpp</ulink>>Defines Finder generators. Finder object is a functor which is able to find a substring matching a specific criteria in the input. Finders are used as a pluggable components for replace, find and split facilities. This header contains generator functions for finders provided in this library.namespace boost {
namespace algorithm {
template<typename ContainerT> unspecified first_finder(const ContainerT &);
template<typename ContainerT, typename PredicateT>
unspecified first_finder(const ContainerT &, PredicateT);
template<typename ContainerT> unspecified last_finder(const ContainerT &);
template<typename ContainerT, typename PredicateT>
unspecified last_finder(const ContainerT &, PredicateT);
template<typename ContainerT>
unspecified nth_finder(const ContainerT &, unsignedint);
template<typename ContainerT, typename PredicateT>
unspecified nth_finder(const ContainerT &, unsignedint, PredicateT);
unspecified head_finder(unsignedint);
unspecified tail_finder(unsignedint);
template<typename PredicateT>
unspecified token_finder(PredicateT,
token_compress_mode_type = token_compress_off);
template<typename ForwardIteratorT>
unspecified range_finder(ForwardIteratorT, ForwardIteratorT);
template<typename ForwardIteratorT>
unspecified range_finder(iterator_range< ForwardIteratorT >);
}
}Function first_finder3boost::algorithm::first_finder"First" finder template<typename ContainerT>
unspecified first_finder(const ContainerT & Search);
template<typename ContainerT, typename PredicateT>
unspecified first_finder(const ContainerT & Search, PredicateT Comp);DescriptionConstruct the first_finder . The finder searches for the first occurrence of the string in a given input. The result is given as an iterator_range delimiting the match.ParametersSearchA substring to be searched for. ReturnsAn instance of the first_finder object Function last_finder3boost::algorithm::last_finder"Last" finder template<typename ContainerT>
unspecified last_finder(const ContainerT & Search);
template<typename ContainerT, typename PredicateT>
unspecified last_finder(const ContainerT & Search, PredicateT Comp);DescriptionConstruct the last_finder . The finder searches for the last occurrence of the string in a given input. The result is given as an iterator_range delimiting the match.ParametersSearchA substring to be searched for. ReturnsAn instance of the last_finder object Function nth_finder3boost::algorithm::nth_finder"Nth" finder template<typename ContainerT>
unspecified nth_finder(const ContainerT & Search, unsignedint Nth);
template<typename ContainerT, typename PredicateT>
unspecified nth_finder(const ContainerT & Search, unsignedint Nth,
PredicateT Comp);DescriptionConstruct the nth_finder . The finder searches for the n-th (zero-indexed) occurrence of the string in a given input. The result is given as an iterator_range delimiting the match.ParametersNthAn index of the match to be find SearchA substring to be searched for. ReturnsAn instance of the nth_finder object Function head_finder3boost::algorithm::head_finder"Head" finder unspecified head_finder(unsignedint N);DescriptionConstruct the head_finder . The finder returns a head of a given input. The head is a prefix of a string up to n elements in size. If an input has less then n elements, whole input is considered a head. The result is given as an iterator_range delimiting the match.ParametersNThe size of the head ReturnsAn instance of the head_finder object Function tail_finder3boost::algorithm::tail_finder"Tail" finder unspecified tail_finder(unsignedint N);DescriptionConstruct the tail_finder . The finder returns a tail of a given input. The tail is a suffix of a string up to n elements in size. If an input has less then n elements, whole input is considered a head. The result is given as an iterator_range delimiting the match.ParametersNThe size of the head ReturnsAn instance of the tail_finder object Function template token_finder3boost::algorithm::token_finder"Token" finder template<typename PredicateT>
unspecified token_finder(PredicateT Pred,
token_compress_mode_type eCompress = token_compress_off);DescriptionConstruct the token_finder . The finder searches for a token specified by a predicate. It is similar to std::find_if algorithm, with an exception that it return a range of instead of a single iterator.If "compress token mode" is enabled, adjacent matching tokens are concatenated into one match. Thus the finder can be used to search for continuous segments of characters satisfying the given predicate.The result is given as an iterator_range delimiting the match.ParametersPredAn element selection predicate eCompressCompress flag ReturnsAn instance of the token_finder object Function range_finder3boost::algorithm::range_finder"Range" finder template<typename ForwardIteratorT>
unspecified range_finder(ForwardIteratorT Begin, ForwardIteratorT End);
template<typename ForwardIteratorT>
unspecified range_finder(iterator_range< ForwardIteratorT > Range);DescriptionConstruct the range_finder . The finder does not perform any operation. It simply returns the given range for any input.ParametersBeginBeginning of the range EndEnd of the range ReturnsAn instance of the range_finger object Header <<ulink url="../../boost/algorithm/string/formatter.hpp">boost/algorithm/string/formatter.hpp</ulink>>Defines Formatter generators. Formatter is a functor which formats a string according to given parameters. A Formatter works in conjunction with a Finder. A Finder can provide additional information for a specific Formatter. An example of such a cooperation is regex_finder and regex_formatter.Formatters are used as pluggable components for replace facilities. This header contains generator functions for the Formatters provided in this library.namespace boost {
namespace algorithm {
template<typename CollectionT>
unspecified const_formatter(const CollectionT &);
template<typename CollectionT> unspecified identity_formatter();
template<typename CollectionT>
unspecified empty_formatter(const CollectionT &);
}
}Function template const_formatter3boost::algorithm::const_formatterConstant formatter. template<typename CollectionT>
unspecified const_formatter(const CollectionT & Format);DescriptionConstruct the const_formatter . Const formatter always returns the same value, regardless of the parameter.ParametersFormatA predefined value used as a result for formating ReturnsAn instance of the const_formatter object. Function template identity_formatter3boost::algorithm::identity_formatterIdentity formatter. template<typename CollectionT> unspecified identity_formatter();DescriptionConstruct the identity_formatter . Identity formatter always returns the parameter.ReturnsAn instance of the identity_formatter object. Function template empty_formatter3boost::algorithm::empty_formatterEmpty formatter. template<typename CollectionT>
unspecified empty_formatter(const CollectionT & );DescriptionConstruct the empty_formatter . Empty formater always returns an empty sequence.ReturnsAn instance of the empty_formatter object. Header <<ulink url="../../boost/algorithm/string/iterator_range.hpp">boost/algorithm/string/iterator_range.hpp</ulink>>Defines the iterator_class and related functions. iterator_range is a simple wrapper of the iterator pair idiom. It provides a rich subset of the Container interface.namespace boost {
namespace algorithm {
template<typename IteratorT> class iterator_range;
template<typename IteratorT, typename Elem, typename Traits>
std::basic_ostream< Elem, Traits > &operator<<(std::basic_ostream< Elem, Traits > &,
const iterator_range< IteratorT > &);
template<typename IteratorT>
iterator_range< IteratorT > make_iterator_range(IteratorT, IteratorT);
template<typename IteratorT>
iterator_range< IteratorT >
make_iterator_range(const std::pair< IteratorT, IteratorT > &);
template<typename SeqT, typename IteratorT>
SeqT copy_iterator_range(const iterator_range< IteratorT > &);
template<typename SeqT, typename IteratorT, typename FuncT>
SeqT transform_iterator_range(const iterator_range< IteratorT > &,
FuncT);
}
}Class template iterator_range3boost::algorithm::iterator_rangeiterator_range class template<typename IteratorT>
class iterator_range {
public:
// typestypedef iterator_range< IteratorT > type; // this type typedefunspecified value_type; // Encapsulated value type. typedefunspecified reference; // Reference type. typedefunspecified difference_type; // Difference type. typedefunspecified size_type; // Size type. typedef IteratorT const_iterator; // const_iterator type typedef IteratorT iterator; // iterator type typedef iterator(iterator_range::* unspecified_bool_type; // Safe bool conversion. // construct/copy/destruct
iterator_range();
iterator_range(iterator, iterator);
iterator_range(const std::pair< IteratorT, IteratorT > &);
iterator_range(const iterator_range &);
template<typename OtherItT>
iterator_range(const iterator_range< OtherItT > &);
iterator_range& operator=(const iterator_range &);
template<typename OtherItT>
iterator_range& operator=(const iterator_range< OtherItT > &);
// public member functionstemplate<typename OtherItT>
booloperator==(const iterator_range< OtherItT > &) const;
template<typename OtherItT>
booloperator!=(const iterator_range< OtherItT > &) const;
IteratorT begin() const;
IteratorT end() const;
bool empty() const;
difference_type size() const;
void swap(iterator_range &) ;
operator unspecified_bool_type() const;
};DescriptionAn iterator_range delimits a range in a sequence by beginning and ending iterators. An iterator_range can be passed to an algorithm which requires a sequence as an input. For example, the toupper() function may most frequently be used on strings, but can also be used on iterator_ranges: boost::tolower( find( s, "UPPERCASE STRING" ) );
Many algorithms working with sequences take a pair of iterators, delimiting a working range, as arguments. The iterator_range class is an encapsulation of a range identified by a pair of iterators. It provides a collection interface, so it is possible to pass an instance to an algorithm requiring a collection as an input. <anchor id="iterator_rangeconstruct-copy-destruct"/><computeroutput>iterator_range</computeroutput> construct/copy/destructiterator_range();iterator_range(iterator Begin, iterator End);iterator_range(const std::pair< IteratorT, IteratorT > & Range);iterator_range(const iterator_range & Other);template<typename OtherItT>
iterator_range(const iterator_range< OtherItT > & Other);This constructor is provided to allow conversion between const and mutable iterator instances of this class template iterator_range& operator=(const iterator_range & Other);template<typename OtherItT>
iterator_range& operator=(const iterator_range< OtherItT > & Other);<anchor id="id339322-bb"/><computeroutput>iterator_range</computeroutput> public member functionstemplate<typename OtherItT>
booloperator==(const iterator_range< OtherItT > & Other) const;Compare operands for equality template<typename OtherItT>
booloperator!=(const iterator_range< OtherItT > & Other) const;Compare operands for non-equality IteratorTbegin() const;Retrieve the begin iterator IteratorTend() const;Retrieve the end iterator boolempty() const;Test whether the range is empty difference_typesize() const;Retrieve the size of the range voidswap(iterator_range & Other) ;Swap two ranges operator unspecified_bool_type() const;Function template operator<<3boost::algorithm::operator<<iterator_range output operator template<typename IteratorT, typename Elem, typename Traits>
std::basic_ostream< Elem, Traits > &operator<<(std::basic_ostream< Elem, Traits > & Os,
const iterator_range< IteratorT > & Range);DescriptionOutput the range to an ostream. Elements are outputed in a sequence without separators. Function template make_iterator_range3boost::algorithm::make_iterator_rangeiterator_range construct helper template<typename IteratorT>
iterator_range< IteratorT >
make_iterator_range(IteratorT Begin, IteratorT End);DescriptionConstruct an iterator_range from a pair of iteratorsParametersBeginA begin iterator EndAn end iterator Returnsiterator_range object Function template make_iterator_range3boost::algorithm::make_iterator_rangeiterator_range construct helper template<typename IteratorT>
iterator_range< IteratorT >
make_iterator_range(const std::pair< IteratorT, IteratorT > & Pair);DescriptionConstruct an iterator_range from a std::pair<> containing the begin and end iterators.ParametersPairA std::pair<> with begin and end iterators Returnsiterator_range object Function template copy_iterator_range3boost::algorithm::copy_iterator_rangecopy a range into a sequence template<typename SeqT, typename IteratorT>
SeqT copy_iterator_range(const iterator_range< IteratorT > & Range);DescriptionConstruct a new sequence of the specified type from the elements in the given rangeParametersRangeAn input range ReturnsNew sequence Function template transform_iterator_range3boost::algorithm::transform_iterator_rangetransform a range into a sequence template<typename SeqT, typename IteratorT, typename FuncT>
SeqT transform_iterator_range(const iterator_range< IteratorT > & Range,
FuncT Func);DescriptionCreate a new sequence from the elements in the range, transformed by a functionParametersFuncTransformation function RangeAn input range ReturnsNew sequence Header <<ulink url="../../boost/algorithm/string/predicate.hpp">boost/algorithm/string/predicate.hpp</ulink>>Defines string-related predicates. The predicates determine whether a substring is contained in the input string under various conditions: a string starts with the substring, ends with the substring, simply contains the substring or if both strings are equal. Additionaly the algorithm all() checks all elements of a container to satisfy a condition.All predicates provide the strong exception guarantee.namespace boost {
namespace algorithm {
template<typename Collection1T, typename Collection2T,
typename PredicateT>
bool starts_with(const Collection1T &, const Collection2T &, PredicateT);
template<typename Collection1T, typename Collection2T>
bool starts_with(const Collection1T &, const Collection2T &);
template<typename Collection1T, typename Collection2T>
bool istarts_with(const Collection1T &, const Collection2T &,
const std::locale & = std::locale());
template<typename Collection1T, typename Collection2T,
typename PredicateT>
bool ends_with(const Collection1T &, const Collection2T &, PredicateT);
template<typename Collection1T, typename Collection2T>
bool ends_with(const Collection1T &, const Collection2T &);
template<typename Collection1T, typename Collection2T>
bool iends_with(const Collection1T &, const Collection2T &,
const std::locale & = std::locale());
template<typename Collection1T, typename Collection2T,
typename PredicateT>
bool contains(const Collection1T &, const Collection2T &, PredicateT);
template<typename Collection1T, typename Collection2T>
bool contains(const Collection1T &, const Collection2T &);
template<typename Collection1T, typename Collection2T>
bool icontains(const Collection1T &, const Collection2T &,
const std::locale & = std::locale());
template<typename Collection1T, typename Collection2T,
typename PredicateT>
bool equals(const Collection1T &, const Collection2T &, PredicateT);
template<typename Collection1T, typename Collection2T>
bool equals(const Collection1T &, const Collection2T &);
template<typename Collection1T, typename Collection2T>
bool iequals(const Collection1T &, const Collection2T &,
const std::locale & = std::locale());
template<typename CollectionT, typename PredicateT>
bool all(const CollectionT &, PredicateT);
}
}Function starts_with3boost::algorithm::starts_with'Starts with' predicate template<typename Collection1T, typename Collection2T, typename PredicateT>
bool starts_with(const Collection1T & Input, const Collection2T & Test,
PredicateT Comp);
template<typename Collection1T, typename Collection2T>
bool starts_with(const Collection1T & Input, const Collection2T & Test);DescriptionThis predicate holds when the test collection is a prefix of the Input. In other words, if the input starts with the test. When the optional predicate is specified, it is used for character-wise comparison.ParametersCompAn element comparison predicate InputAn input sequence TestA test sequence ReturnsThe result of the testNotesThis function provides the strong exception-safety guarantee Function template istarts_with3boost::algorithm::istarts_with'Starts with' predicate ( case insensitive ) template<typename Collection1T, typename Collection2T>
bool istarts_with(const Collection1T & Input, const Collection2T & Test,
const std::locale & Loc = std::locale());DescriptionThis predicate holds when the test container is a prefix of the Input. In other words, if the input starts with the test. Elements are compared case insensitively.ParametersInputAn input sequence LocA locale used for case insensitive comparison TestA test sequence ReturnsThe result of the testNotesThis function provides the strong exception-safety guarantee Function ends_with3boost::algorithm::ends_with'Ends with' predicate template<typename Collection1T, typename Collection2T, typename PredicateT>
bool ends_with(const Collection1T & Input, const Collection2T & Test,
PredicateT Comp);
template<typename Collection1T, typename Collection2T>
bool ends_with(const Collection1T & Input, const Collection2T & Test);DescriptionThis predicate holds when the test container is a suffix of the Input. In other words, if the input ends with the test. When the optional predicate is specified, it is used for character-wise comparison.ParametersCompAn element comparison predicate InputAn input sequence TestA test sequence ReturnsThe result of the testNotesThis function provides the strong exception-safety guarantee Function template iends_with3boost::algorithm::iends_with'Ends with' predicate ( case insensitive ) template<typename Collection1T, typename Collection2T>
bool iends_with(const Collection1T & Input, const Collection2T & Test,
const std::locale & Loc = std::locale());DescriptionThis predicate holds when the test container is a suffix of the Input. In other words, if the input ends with the test. Elements are compared case insensitively.ParametersInputAn input sequence LocA locale used for case insensitive comparison TestA test sequence ReturnsThe result of the testNotesThis function provides the strong exception-safety guarantee Function contains3boost::algorithm::contains'Contains' predicate template<typename Collection1T, typename Collection2T, typename PredicateT>
bool contains(const Collection1T & Input, const Collection2T & Test,
PredicateT Comp);
template<typename Collection1T, typename Collection2T>
bool contains(const Collection1T & Input, const Collection2T & Test);DescriptionThis predicate holds when the test container is contained in the Input. When the optional predicate is specified, it is used for character-wise comparison.ParametersCompAn element comparison predicate InputAn input sequence TestA test sequence ReturnsThe result of the testNotesThis function provides the strong exception-safety guarantee Function template icontains3boost::algorithm::icontains'Contains' predicate ( case insensitive ) template<typename Collection1T, typename Collection2T>
bool icontains(const Collection1T & Input, const Collection2T & Test,
const std::locale & Loc = std::locale());DescriptionThis predicate holds when the test container is contained in the Input. Elements are compared case insensitively.ParametersInputAn input sequence LocA locale used for case insensitive comparison TestA test sequence ReturnsThe result of the testNotesThis function provides the strong exception-safety guarantee Function equals3boost::algorithm::equals'Equals' predicate template<typename Collection1T, typename Collection2T, typename PredicateT>
bool equals(const Collection1T & Input, const Collection2T & Test,
PredicateT Comp);
template<typename Collection1T, typename Collection2T>
bool equals(const Collection1T & Input, const Collection2T & Test);DescriptionThis predicate holds when the test container is equal to the input container i.e. all elements in both containers are same. When the optional predicate is specified, it is used for character-wise comparison.ParametersCompAn element comparison predicate InputAn input sequence TestA test sequence ReturnsThe result of the testNotesThis is a two-way version of std::equal algorithmThis function provides the strong exception-safety guarantee Function template iequals3boost::algorithm::iequals'Equals' predicate ( casa insensitive ) template<typename Collection1T, typename Collection2T>
bool iequals(const Collection1T & Input, const Collection2T & Test,
const std::locale & Loc = std::locale());DescriptionThis predicate holds when the test container is equal to the input container i.e. all elements in both containers are same. Elements are compared case insensitively.ParametersInputAn input sequence LocA locale used for case insensitive comparison TestA test sequence ReturnsThe result of the testNotesThis is a two-way version of std::equal algorithmThis function provides the strong exception-safety guarantee Function template all3boost::algorithm::all'All' predicate template<typename CollectionT, typename PredicateT>
bool all(const CollectionT & Input, PredicateT Pred);DescriptionThis predicate holds it all its elements satisfy a given condition, represented by the predicate.ParametersInputAn input sequence PredA predicate ReturnsThe result of the testNotesThis function provides the strong exception-safety guarantee Header <<ulink url="../../boost/algorithm/string/regex.hpp">boost/algorithm/string/regex.hpp</ulink>>Defines regex variants of the algorithms.namespace boost {
namespace algorithm {
template<typename CollectionT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT>
iterator_range< typename result_iterator_of< CollectionT >::type >
find_regex(CollectionT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
match_flag_type = match_default);
template<typename OutputIteratorT, typename CollectionT, typename CharT,
typename RegexTraitsT, typename RegexAllocatorT,
typename FormatStringTraitsT, typename FormatStringAllocatorT>
OutputIteratorT
replace_regex_copy(OutputIteratorT, const CollectionT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
const std::basic_string< CharT, FormatStringTraitsT, FormatStringAllocatorT > &,
match_flag_type = match_default|format_default);
template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT, typename FormatStringTraitsT,
typename FormatStringAllocatorT>
SequenceT replace_regex_copy(const SequenceT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
const std::basic_string< CharT, FormatStringTraitsT, FormatStringAllocatorT > &,
match_flag_type = match_default|format_default);
template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT, typename FormatStringTraitsT,
typename FormatStringAllocatorT>
void replace_regex(SequenceT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
const std::basic_string< CharT, FormatStringTraitsT, FormatStringAllocatorT > &,
match_flag_type = match_default|format_default);
template<typename OutputIteratorT, typename CollectionT, typename CharT,
typename RegexTraitsT, typename RegexAllocatorT,
typename FormatStringTraitsT, typename FormatStringAllocatorT>
OutputIteratorT
replace_all_regex_copy(OutputIteratorT, const CollectionT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
const std::basic_string< CharT, FormatStringTraitsT, FormatStringAllocatorT > &,
match_flag_type = match_default|format_default);
template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT, typename FormatStringTraitsT,
typename FormatStringAllocatorT>
SequenceT replace_all_regex_copy(const SequenceT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
const std::basic_string< CharT, FormatStringTraitsT, FormatStringAllocatorT > &,
match_flag_type = match_default|format_default);
template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT, typename FormatStringTraitsT,
typename FormatStringAllocatorT>
void replace_all_regex(SequenceT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
const std::basic_string< CharT, FormatStringTraitsT, FormatStringAllocatorT > &,
match_flag_type = match_default|format_default);
template<typename OutputIteratorT, typename CollectionT, typename CharT,
typename RegexTraitsT, typename RegexAllocatorT>
OutputIteratorT
erase_regex_copy(OutputIteratorT, const CollectionT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
match_flag_type = match_default);
template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT>
SequenceT erase_regex_copy(const SequenceT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
match_flag_type = match_default);
template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT>
void erase_regex(SequenceT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
match_flag_type = match_default);
template<typename OutputIteratorT, typename CollectionT, typename CharT,
typename RegexTraitsT, typename RegexAllocatorT>
OutputIteratorT
erase_all_regex_copy(OutputIteratorT, const CollectionT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
match_flag_type = match_default);
template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT>
SequenceT erase_all_regex_copy(const SequenceT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
match_flag_type = match_default);
template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT>
void erase_all_regex(SequenceT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
match_flag_type = match_default);
template<typename SequenceSequenceT, typename CollectionT, typename CharT,
typename RegexTraitsT, typename RegexAllocatorT>
SequenceSequenceT &
find_all_regex(SequenceSequenceT &, const CollectionT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
match_flag_type = match_default);
template<typename SequenceSequenceT, typename CollectionT, typename CharT,
typename RegexTraitsT, typename RegexAllocatorT>
SequenceSequenceT &
split_regex(SequenceSequenceT &, const CollectionT &,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
match_flag_type = match_default);
}
}Function template find_regex3boost::algorithm::find_regexFind regex algorithm. template<typename CollectionT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT>
iterator_range< typename result_iterator_of< CollectionT >::type >
find_regex(CollectionT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
match_flag_type Flags = match_default);DescriptionSearch for a substring matching the given regex in the input.ParametersFlagsRegex options InputA container which will be searched. RxA regular expression ReturnsAn iterator_range delimiting the match. Returned iterator is either InputContainerT::iterator or InputContainerT::const_iterator , depending on the constness of the input parameter.NotesThis function provides the strong exception-safety guarantee Function replace_regex_copy3boost::algorithm::replace_regex_copyReplace regex algorithm. template<typename OutputIteratorT, typename CollectionT, typename CharT,
typename RegexTraitsT, typename RegexAllocatorT,
typename FormatStringTraitsT, typename FormatStringAllocatorT>
OutputIteratorT
replace_regex_copy(OutputIteratorT Output, const CollectionT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
const std::basic_string< CharT, FormatStringTraitsT, FormatStringAllocatorT > & Format,
match_flag_type Flags = match_default|format_default);
template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT, typename FormatStringTraitsT,
typename FormatStringAllocatorT>
SequenceT replace_regex_copy(const SequenceT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
const std::basic_string< CharT, FormatStringTraitsT, FormatStringAllocatorT > & Format,
match_flag_type Flags = match_default|format_default);DescriptionSearch for a substring matching given regex and format it with the specified format. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersFlagsRegex options FormatRegex format definition InputAn input string OutputAn output iterator to which the result will be copied RxA regular expression ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template replace_regex3boost::algorithm::replace_regexReplace regex algorithm. template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT, typename FormatStringTraitsT,
typename FormatStringAllocatorT>
void replace_regex(SequenceT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
const std::basic_string< CharT, FormatStringTraitsT, FormatStringAllocatorT > & Format,
match_flag_type Flags = match_default|format_default);DescriptionSearch for a substring matching given regex and format it with the specified format. The input string is modified in-place.ParametersFlagsRegex options FormatRegex format definition InputAn input string RxA regular expression Function replace_all_regex_copy3boost::algorithm::replace_all_regex_copyReplace all regex algorithm. template<typename OutputIteratorT, typename CollectionT, typename CharT,
typename RegexTraitsT, typename RegexAllocatorT,
typename FormatStringTraitsT, typename FormatStringAllocatorT>
OutputIteratorT
replace_all_regex_copy(OutputIteratorT Output, const CollectionT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
const std::basic_string< CharT, FormatStringTraitsT, FormatStringAllocatorT > & Format,
match_flag_type Flags = match_default|format_default);
template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT, typename FormatStringTraitsT,
typename FormatStringAllocatorT>
SequenceT replace_all_regex_copy(const SequenceT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
const std::basic_string< CharT, FormatStringTraitsT, FormatStringAllocatorT > & Format,
match_flag_type Flags = match_default|format_default);DescriptionFormat all substrings, matching given regex, with the specified format. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersFlagsRegex options FormatRegex format definition InputAn input string OutputAn output iterator to which the result will be copied RxA regular expression ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template replace_all_regex3boost::algorithm::replace_all_regexReplace all regex algorithm. template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT, typename FormatStringTraitsT,
typename FormatStringAllocatorT>
void replace_all_regex(SequenceT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
const std::basic_string< CharT, FormatStringTraitsT, FormatStringAllocatorT > & Format,
match_flag_type Flags = match_default|format_default);DescriptionFormat all substrings, matching given regex, with the specified format. The input string is modified in-place.ParametersFlagsRegex options FormatRegex format definition InputAn input string RxA regular expression Function erase_regex_copy3boost::algorithm::erase_regex_copyErase regex algorithm. template<typename OutputIteratorT, typename CollectionT, typename CharT,
typename RegexTraitsT, typename RegexAllocatorT>
OutputIteratorT
erase_regex_copy(OutputIteratorT Output, const CollectionT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
match_flag_type Flags = match_default);
template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT>
SequenceT erase_regex_copy(const SequenceT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
match_flag_type Flags = match_default);DescriptionRemove a substring matching given regex from the input. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersFlagsRegex options InputAn input string OutputAn output iterator to which the result will be copied RxA regular expression ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template erase_regex3boost::algorithm::erase_regexErase regex algorithm. template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT>
void erase_regex(SequenceT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
match_flag_type Flags = match_default);DescriptionRemove a substring matching given regex from the input. The input string is modified in-place.ParametersFlagsRegex options InputAn input string RxA regular expression Function erase_all_regex_copy3boost::algorithm::erase_all_regex_copyErase all regex algorithm. template<typename OutputIteratorT, typename CollectionT, typename CharT,
typename RegexTraitsT, typename RegexAllocatorT>
OutputIteratorT
erase_all_regex_copy(OutputIteratorT Output, const CollectionT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
match_flag_type Flags = match_default);
template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT>
SequenceT erase_all_regex_copy(const SequenceT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
match_flag_type Flags = match_default);DescriptionErase all substrings, matching given regex, from the input. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersFlagsRegex options InputAn input string OutputAn output iterator to which the result will be copied RxA regular expression ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template erase_all_regex3boost::algorithm::erase_all_regexErase all regex algorithm. template<typename SequenceT, typename CharT, typename RegexTraitsT,
typename RegexAllocatorT>
void erase_all_regex(SequenceT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
match_flag_type Flags = match_default);DescriptionErase all substrings, matching given regex, from the input. The input string is modified in-place.ParametersFlagsRegex options InputAn input string RxA regular expression Function template find_all_regex3boost::algorithm::find_all_regexFind all regex algorithm. template<typename SequenceSequenceT, typename CollectionT, typename CharT,
typename RegexTraitsT, typename RegexAllocatorT>
SequenceSequenceT &
find_all_regex(SequenceSequenceT & Result, const CollectionT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
match_flag_type Flags = match_default);DescriptionThis algorithm finds all substrings matching the give regex in the input.Each part is copied and added as a new element to the output container. Thus the result container must be able to hold copies of the matches (in a compatible structure like std::string) or a reference to it (e.g. using the iterator range class). Examples of such a container are std::vector<std::string> or std::list<boost::iterator_range<std::string::iterator>>ParametersFlagsRegex options InputA container which will be searched. ResultA container that can hold copies of references to the substrings. RxA regular expression ReturnsA reference to the resultNotesPrior content of the result will be overwritten.This function provides the strong exception-safety guarantee Function template split_regex3boost::algorithm::split_regexSplit regex algorithm. template<typename SequenceSequenceT, typename CollectionT, typename CharT,
typename RegexTraitsT, typename RegexAllocatorT>
SequenceSequenceT &
split_regex(SequenceSequenceT & Result, const CollectionT & Input,
const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
match_flag_type Flags = match_default);DescriptionTokenize expression. This function is equivalent to C strtok. Input sequence is split into tokens, separated by separators. Separator is an every match of the given regex. Each part is copied and added as a new element to the output container. Thus the result container must be able to hold copies of the matches (in a compatible structure like std::string) or a reference to it (e.g. using the iterator range class). Examples of such a container are std::vector<std::string> or std::list<boost::iterator_range<std::string::iterator>>ParametersFlagsRegex options InputA container which will be searched. ResultA container that can hold copies of references to the substrings. RxA regular expression ReturnsA reference to the resultNotesPrior content of the result will be overwritten.This function provides the strong exception-safety guarantee Header <<ulink url="../../boost/algorithm/string/regex_find_format.hpp">boost/algorithm/string/regex_find_format.hpp</ulink>>Defines the regex_finder and regex_formatter generators. These two functors are designed to work together. regex_formatter uses additional information about a match contained in the regex_finder search result.namespace boost {
namespace algorithm {
template<typename CharT, typename RegexTraitsT, typename RegexAllocatorT>
unspecified regex_finder(const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > &,
match_flag_type = match_default);
template<typename CharT, typename TraitsT, typename AllocT>
unspecified regex_formatter(const std::basic_string< CharT, TraitsT, AllocT > &,
match_flag_type = format_default);
}
}Function template regex_finder3boost::algorithm::regex_finder"Regex" finder template<typename CharT, typename RegexTraitsT, typename RegexAllocatorT>
unspecified regex_finder(const reg_expression< CharT, RegexTraitsT, RegexAllocatorT > & Rx,
match_flag_type MatchFlags = match_default);DescriptionConstruct the regex_finder . Finder uses the regex engine to search for a match. Result is given in regex_search_result . This is an extension of the iterator_range. In addition it containes match results from the regex_search algorithm.ParametersMatchFlagsRegex search options RxA regular expression ReturnsAn instance of the regex_finder object Function template regex_formatter3boost::algorithm::regex_formatterRegex formatter. template<typename CharT, typename TraitsT, typename AllocT>
unspecified regex_formatter(const std::basic_string< CharT, TraitsT, AllocT > & Format,
match_flag_type Flags = format_default);DescriptionConstruct the regex_formatter . Regex formatter uses the regex engine to format a match found by the regex_finder . This formatted it designed to closely cooperate with regex_finder .ParametersFlagsFormat flags FormatRegex format definition ReturnsAn instance of the regex_formatter functor Header <<ulink url="../../boost/algorithm/string/replace.hpp">boost/algorithm/string/replace.hpp</ulink>>Defines various replace algorithms. Each algorithm replaces part(s) of the input according to set of searching and replace criteria.namespace boost {
namespace algorithm {
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
replace_range_copy(OutputIteratorT, const Collection1T &,
const iterator_range< typename const_iterator_of< Collection1T >::type > &,
const Collection2T &);
template<typename SequenceT, typename CollectionT>
SequenceT replace_range_copy(const SequenceT &,
const iterator_range< typename const_iterator_of< SequenceT >::type > &,
const CollectionT &);
template<typename SequenceT, typename CollectionT>
void replace_range(SequenceT &,
const iterator_range< typename iterator_of< SequenceT >::type > &,
const CollectionT &);
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
replace_first_copy(OutputIteratorT, const Collection1T &,
const Collection2T &, const Collection3T &);
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT replace_first_copy(const SequenceT &, const Collection1T &,
const Collection2T &);
template<typename SequenceT, typename Collection1T, typename Collection2T>
void replace_first(SequenceT &, const Collection1T &,
const Collection2T &);
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
ireplace_first_copy(OutputIteratorT, const Collection1T &,
const Collection2T &, const Collection3T &,
const std::locale & = std::locale());
template<typename SequenceT, typename Collection2T, typename Collection1T>
SequenceT ireplace_first_copy(const SequenceT &, const Collection2T &,
const Collection1T &,
const std::locale & = std::locale());
template<typename SequenceT, typename Collection1T, typename Collection2T>
void ireplace_first(SequenceT &, const Collection1T &,
const Collection2T &,
const std::locale & = std::locale());
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
replace_last_copy(OutputIteratorT, const Collection1T &,
const Collection2T &, const Collection3T &);
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT replace_last_copy(const SequenceT &, const Collection1T &,
const Collection2T &);
template<typename SequenceT, typename Collection1T, typename Collection2T>
void replace_last(SequenceT &, const Collection1T &,
const Collection2T &);
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
ireplace_last_copy(OutputIteratorT, const Collection1T &,
const Collection2T &, const Collection3T &,
const std::locale & = std::locale());
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT ireplace_last_copy(const SequenceT &, const Collection1T &,
const Collection2T &,
const std::locale & = std::locale());
template<typename SequenceT, typename Collection1T, typename Collection2T>
void ireplace_last(SequenceT &, const Collection1T &,
const Collection2T &,
const std::locale & = std::locale());
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
replace_nth_copy(OutputIteratorT, const Collection1T &,
const Collection2T &, unsignedint,
const Collection3T &);
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT replace_nth_copy(const SequenceT &, const Collection1T &,
unsignedint, const Collection2T &);
template<typename SequenceT, typename Collection1T, typename Collection2T>
void replace_nth(SequenceT &, const Collection1T &, unsignedint,
const Collection2T &);
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
ireplace_nth_copy(OutputIteratorT, const Collection1T &,
const Collection2T &, unsignedint,
const Collection3T &,
const std::locale & = std::locale());
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT ireplace_nth_copy(const SequenceT &, const Collection1T &,
unsignedint, const Collection2T &,
const std::locale & = std::locale());
template<typename SequenceT, typename Collection1T, typename Collection2T>
void ireplace_nth(SequenceT &, const Collection1T &, unsignedint,
const Collection2T &,
const std::locale & = std::locale());
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
replace_all_copy(OutputIteratorT, const Collection1T &,
const Collection2T &, const Collection3T &);
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT replace_all_copy(const SequenceT &, const Collection1T &,
const Collection2T &);
template<typename SequenceT, typename Collection1T, typename Collection2T>
void replace_all(SequenceT &, const Collection1T &,
const Collection2T &);
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
ireplace_all_copy(OutputIteratorT, const Collection1T &,
const Collection2T &, const Collection3T &,
const std::locale & = std::locale());
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT ireplace_all_copy(const SequenceT &, const Collection1T &,
const Collection2T &,
const std::locale & = std::locale());
template<typename SequenceT, typename Collection1T, typename Collection2T>
void ireplace_all(SequenceT &, const Collection1T &,
const Collection2T &,
const std::locale & = std::locale());
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
replace_head_copy(OutputIteratorT, const Collection1T &, unsignedint,
const Collection2T &);
template<typename SequenceT, typename CollectionT>
SequenceT replace_head_copy(const SequenceT &, unsignedint,
const CollectionT &);
template<typename SequenceT, typename CollectionT>
void replace_head(SequenceT &, unsignedint, const CollectionT &);
template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
replace_tail_copy(OutputIteratorT, const Collection1T &, unsignedint,
const Collection2T &);
template<typename SequenceT, typename CollectionT>
SequenceT replace_tail_copy(const SequenceT &, unsignedint,
const CollectionT &);
template<typename SequenceT, typename CollectionT>
void replace_tail(SequenceT &, unsignedint, const CollectionT &);
}
}Function replace_range_copy3boost::algorithm::replace_range_copyReplace range algorithm. template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
replace_range_copy(OutputIteratorT Output, const Collection1T & Input,
const iterator_range< typename const_iterator_of< Collection1T >::type > & SearchRange,
const Collection2T & Format);
template<typename SequenceT, typename CollectionT>
SequenceT replace_range_copy(const SequenceT & Input,
const iterator_range< typename const_iterator_of< SequenceT >::type > & SearchRange,
const CollectionT & Format);DescriptionReplace the given range in the input string. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersFormatA substitute string InputAn input string OutputAn output iterator to which the result will be copied SearchRangeA range in the input to be substituted ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template replace_range3boost::algorithm::replace_rangeReplace range algorithm. template<typename SequenceT, typename CollectionT>
void replace_range(SequenceT & Input,
const iterator_range< typename iterator_of< SequenceT >::type > & SearchRange,
const CollectionT & Format);DescriptionReplace the given range in the input string. The input sequence is modified in-place.ParametersFormatA substitute string InputAn input string SearchRangeA range in the input to be substituted Function replace_first_copy3boost::algorithm::replace_first_copyReplace first algorithm. template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
replace_first_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search,
const Collection3T & Format);
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT replace_first_copy(const SequenceT & Input,
const Collection1T & Search,
const Collection2T & Format);DescriptionReplace the first match of the search substring in the input with the format string. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersFormatA substitute string InputAn input string OutputAn output iterator to which the result will be copied SearchA substring to be searched for ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template replace_first3boost::algorithm::replace_firstReplace first algorithm. template<typename SequenceT, typename Collection1T, typename Collection2T>
void replace_first(SequenceT & Input, const Collection1T & Search,
const Collection2T & Format);Descriptionreplace the first match of the search substring in the input with the format string. The input sequence is modified in-place.ParametersFormatA substitute string InputAn input string SearchA substring to be searched for Function ireplace_first_copy3boost::algorithm::ireplace_first_copyReplace first algorithm ( case insensitive ). template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
ireplace_first_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search,
const Collection3T & Format,
const std::locale & Loc = std::locale());
template<typename SequenceT, typename Collection2T, typename Collection1T>
SequenceT ireplace_first_copy(const SequenceT & Input,
const Collection2T & Search,
const Collection1T & Format,
const std::locale & Loc = std::locale());DescriptionReplace the first match of the search substring in the input with the format string. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator. Searching is case insensitive.ParametersFormatA substitute string InputAn input string LocA locale used for case insensitive comparison OutputAn output iterator to which the result will be copied SearchA substring to be searched for ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template ireplace_first3boost::algorithm::ireplace_firstReplace first algorithm ( case insensitive ). template<typename SequenceT, typename Collection1T, typename Collection2T>
void ireplace_first(SequenceT & Input, const Collection1T & Search,
const Collection2T & Format,
const std::locale & Loc = std::locale());DescriptionReplace the first match of the search substring in the input with the format string. Input sequence is modified in-place. Searching is case insensitive.ParametersFormatA substitute string InputAn input string LocA locale used for case insensitive comparison SearchA substring to be searched for Function replace_last_copy3boost::algorithm::replace_last_copyReplace last algorithm. template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
replace_last_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search, const Collection3T & Format);
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT replace_last_copy(const SequenceT & Input,
const Collection1T & Search,
const Collection2T & Format);DescriptionReplace the last match of the search string in the input with the format string. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersFormatA substitute string InputAn input string OutputAn output iterator to which the result will be copied SearchA substring to be searched for ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template replace_last3boost::algorithm::replace_lastReplace last algorithm. template<typename SequenceT, typename Collection1T, typename Collection2T>
void replace_last(SequenceT & Input, const Collection1T & Search,
const Collection2T & Format);DescriptionReplace the last match of the search string in the input with the format string. Input sequence is modified in-place.ParametersFormatA substitute string InputAn input string SearchA substring to be searched for Function ireplace_last_copy3boost::algorithm::ireplace_last_copyReplace last algorithm ( case insensitive ). template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
ireplace_last_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search,
const Collection3T & Format,
const std::locale & Loc = std::locale());
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT ireplace_last_copy(const SequenceT & Input,
const Collection1T & Search,
const Collection2T & Format,
const std::locale & Loc = std::locale());DescriptionReplace the last match of the search string in the input with the format string. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator. Searching is case insensitive.ParametersFormatA substitute string InputAn input string LocA locale used for case insensitive comparison OutputAn output iterator to which the result will be copied SearchA substring to be searched for ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template ireplace_last3boost::algorithm::ireplace_lastReplace last algorithm ( case insensitive ). template<typename SequenceT, typename Collection1T, typename Collection2T>
void ireplace_last(SequenceT & Input, const Collection1T & Search,
const Collection2T & Format,
const std::locale & Loc = std::locale());DescriptionReplace the last match of the search string in the input with the format string.The input sequence is modified in-place. Searching is case insensitive.ParametersFormatA substitute string InputAn input string LocA locale used for case insensitive comparison SearchA substring to be searched for ReturnsA reference to the modified input Function replace_nth_copy3boost::algorithm::replace_nth_copyReplace nth algorithm. template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
replace_nth_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search, unsignedint Nth,
const Collection3T & Format);
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT replace_nth_copy(const SequenceT & Input,
const Collection1T & Search, unsignedint Nth,
const Collection2T & Format);DescriptionReplace an Nth (zero-indexed) match of the search string in the input with the format string. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersFormatA substitute string InputAn input string NthAn index of the match to be replaced. The index is 0-based. OutputAn output iterator to which the result will be copied SearchA substring to be searched for ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template replace_nth3boost::algorithm::replace_nthReplace nth algorithm. template<typename SequenceT, typename Collection1T, typename Collection2T>
void replace_nth(SequenceT & Input, const Collection1T & Search,
unsignedint Nth, const Collection2T & Format);DescriptionReplace an Nth (zero-indexed) match of the search string in the input with the format string. Input sequence is modified in-place.ParametersFormatA substitute string InputAn input string NthAn index of the match to be replaced. The index is 0-based. SearchA substring to be searched for Function ireplace_nth_copy3boost::algorithm::ireplace_nth_copyReplace nth algorithm ( case insensitive ). template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
ireplace_nth_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search, unsignedint Nth,
const Collection3T & Format,
const std::locale & Loc = std::locale());
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT ireplace_nth_copy(const SequenceT & Input,
const Collection1T & Search, unsignedint Nth,
const Collection2T & Format,
const std::locale & Loc = std::locale());DescriptionReplace an Nth (zero-indexed) match of the search string in the input with the format string. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator. Searching is case insensitive.ParametersFormatA substitute string InputAn input string LocA locale used for case insensitive comparison NthAn index of the match to be replaced. The index is 0-based. OutputAn output iterator to which the result will be copied SearchA substring to be searched for ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template ireplace_nth3boost::algorithm::ireplace_nthReplace nth algorithm ( case insensitive ). template<typename SequenceT, typename Collection1T, typename Collection2T>
void ireplace_nth(SequenceT & Input, const Collection1T & Search,
unsignedint Nth, const Collection2T & Format,
const std::locale & Loc = std::locale());DescriptionReplace an Nth (zero-indexed) match of the search string in the input with the format string. Input sequence is modified in-place. Searching is case insensitive.ParametersFormatA substitute string InputAn input string LocA locale used for case insensitive comparison NthAn index of the match to be replaced. The index is 0-based. SearchA substring to be searched for Function replace_all_copy3boost::algorithm::replace_all_copyReplace all algorithm. template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
replace_all_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search, const Collection3T & Format);
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT replace_all_copy(const SequenceT & Input,
const Collection1T & Search,
const Collection2T & Format);DescriptionReplace all occurrences of the search string in the input with the format string. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersFormatA substitute string InputAn input string OutputAn output iterator to which the result will be copied SearchA substring to be searched for ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template replace_all3boost::algorithm::replace_allReplace all algorithm. template<typename SequenceT, typename Collection1T, typename Collection2T>
void replace_all(SequenceT & Input, const Collection1T & Search,
const Collection2T & Format);DescriptionReplace all occurrences of the search string in the input with the format string. The input sequence is modified in-place.ParametersFormatA substitute string InputAn input string SearchA substring to be searched for ReturnsA reference to the modified input Function ireplace_all_copy3boost::algorithm::ireplace_all_copyReplace all algorithm ( case insensitive ). template<typename OutputIteratorT, typename Collection1T,
typename Collection2T, typename Collection3T>
OutputIteratorT
ireplace_all_copy(OutputIteratorT Output, const Collection1T & Input,
const Collection2T & Search, const Collection3T & Format,
const std::locale & Loc = std::locale());
template<typename SequenceT, typename Collection1T, typename Collection2T>
SequenceT ireplace_all_copy(const SequenceT & Input,
const Collection1T & Search,
const Collection2T & Format,
const std::locale & Loc = std::locale());DescriptionReplace all occurrences of the search string in the input with the format string. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator. Searching is case insensitive.ParametersFormatA substitute string InputAn input string LocA locale used for case insensitive comparison OutputAn output iterator to which the result will be copied SearchA substring to be searched for ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template ireplace_all3boost::algorithm::ireplace_allReplace all algorithm ( case insensitive ). template<typename SequenceT, typename Collection1T, typename Collection2T>
void ireplace_all(SequenceT & Input, const Collection1T & Search,
const Collection2T & Format,
const std::locale & Loc = std::locale());DescriptionReplace all occurrences of the search string in the input with the format string.The input sequence is modified in-place. Searching is case insensitive.ParametersFormatA substitute string InputAn input string LocA locale used for case insensitive comparison SearchA substring to be searched for Function replace_head_copy3boost::algorithm::replace_head_copyReplace head algorithm. template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
replace_head_copy(OutputIteratorT Output, const Collection1T & Input,
unsignedint N, const Collection2T & Format);
template<typename SequenceT, typename CollectionT>
SequenceT replace_head_copy(const SequenceT & Input, unsignedint N,
const CollectionT & Format);DescriptionReplace the head of the input with the given format string. The head is a prefix of a string of given size. If the sequence is shorter then required, whole string if considered to be the head. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersFormatA substitute string InputAn input string NLength of the head OutputAn output iterator to which the result will be copied ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template replace_head3boost::algorithm::replace_headReplace head algorithm. template<typename SequenceT, typename CollectionT>
void replace_head(SequenceT & Input, unsignedint N,
const CollectionT & Format);DescriptionReplace the head of the input with the given format string. The head is a prefix of a string of given size. If the sequence is shorter then required, the whole string is considered to be the head. The input sequence is modified in-place.ParametersFormatA substitute string InputAn input string NLength of the head Function replace_tail_copy3boost::algorithm::replace_tail_copyReplace tail algorithm. template<typename OutputIteratorT, typename Collection1T,
typename Collection2T>
OutputIteratorT
replace_tail_copy(OutputIteratorT Output, const Collection1T & Input,
unsignedint N, const Collection2T & Format);
template<typename SequenceT, typename CollectionT>
SequenceT replace_tail_copy(const SequenceT & Input, unsignedint N,
const CollectionT & Format);DescriptionReplace the tail of the input with the given format string. The tail is a suffix of a string of given size. If the sequence is shorter then required, whole string is considered to be the tail. The result is a modified copy of the input. It is returned as a sequence or copied to the output iterator.ParametersFormatA substitute string InputAn input string NLength of the tail OutputAn output iterator to which the result will be copied ReturnsAn output iterator pointing just after the last inserted character or a modified copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template replace_tail3boost::algorithm::replace_tailReplace tail algorithm. template<typename SequenceT, typename CollectionT>
void replace_tail(SequenceT & Input, unsignedint N,
const CollectionT & Format);DescriptionReplace the tail of the input with the given format sequence. The tail is a suffix of a string of given size. If the sequence is shorter then required, the whole string is considered to be the tail. The input sequence is modified in-place.ParametersFormatA substitute string InputAn input string NLength of the tail Header <<ulink url="../../boost/algorithm/string/sequence_traits.hpp">boost/algorithm/string/sequence_traits.hpp</ulink>>Traits defined in this header are used by various algorithms to achieve better performance for specific containers. Traits provide fail-safe defaults. If a container supports some of these features, it is possible to specialize the specific trait for this container. For lacking compilers, it is possible of define an override for a specific tester function.Due to a language restriction, it is not currently possible to define specializations for stl containers without including the corresponding header. To decrease the overhead needed by this inclusion, user can selectively include a specialization header for a specific container. They are located in boost/algorithm/string/stl directory. Alternatively she can include boost/algorithm/string/std_collection_traits.hpp header which contains specializations for all stl containers.namespace boost {
namespace algorithm {
template<typename T> class has_native_replace;
template<typename T> class has_stable_iterators;
template<typename T> class has_const_time_insert;
template<typename T> class has_const_time_erase;
}
}Class template has_native_replace3boost::algorithm::has_native_replaceNative replace trait. template<typename T>
class has_native_replace {
public:
// typestypedef mpl::bool_< value > type;
// public member functions BOOST_STATIC_CONSTANT(bool, value = false) ;
};DescriptionThis trait specifies that the sequence has std::string like replace method <anchor id="id404694-bb"/><computeroutput>has_native_replace</computeroutput> public member functionsBOOST_STATIC_CONSTANT(bool , value = false) ;Class template has_stable_iterators3boost::algorithm::has_stable_iteratorsStable iterators trait. template<typename T>
class has_stable_iterators {
public:
// typestypedef mpl::bool_< value > type;
// public member functions BOOST_STATIC_CONSTANT(bool, value = false) ;
};DescriptionThis trait specifies that the sequence has stable iterators. It means that operations like insert/erase/replace do not invalidate iterators. <anchor id="id430089-bb"/><computeroutput>has_stable_iterators</computeroutput> public member functionsBOOST_STATIC_CONSTANT(bool , value = false) ;Class template has_const_time_insert3boost::algorithm::has_const_time_insertConst time insert trait. template<typename T>
class has_const_time_insert {
public:
// typestypedef mpl::bool_< value > type;
// public member functions BOOST_STATIC_CONSTANT(bool, value = false) ;
};DescriptionThis trait specifies that the sequence's insert method has constant time complexity. <anchor id="id502277-bb"/><computeroutput>has_const_time_insert</computeroutput> public member functionsBOOST_STATIC_CONSTANT(bool , value = false) ;Class template has_const_time_erase3boost::algorithm::has_const_time_eraseConst time erase trait. template<typename T>
class has_const_time_erase {
public:
// typestypedef mpl::bool_< value > type;
// public member functions BOOST_STATIC_CONSTANT(bool, value = false) ;
};DescriptionThis trait specifies that the sequence's erase method has constant time complexity. <anchor id="id313377-bb"/><computeroutput>has_const_time_erase</computeroutput> public member functionsBOOST_STATIC_CONSTANT(bool , value = false) ;Header <<ulink url="../../boost/algorithm/string/split.hpp">boost/algorithm/string/split.hpp</ulink>>Defines basic split algorithms. Split algorithms can be used to divide a string into several parts according to given criteria.Each part is copied and added as a new element to the output container. Thus the result container must be able to hold copies of the matches (in a compatible structure like std::string) or a reference to it (e.g. using the iterator range class). Examples of such a container are std::vector<std::string> or std::list<boost::iterator_range<std::string::iterator>>namespace boost {
namespace algorithm {
template<typename SequenceSequenceT, typename Collection1T,
typename Collection2T>
SequenceSequenceT &
find_all(SequenceSequenceT &, Collection1T &, const Collection2T &);
template<typename SequenceSequenceT, typename Collection1T,
typename Collection2T>
SequenceSequenceT &
ifind_all(SequenceSequenceT &, Collection1T &, const Collection2T &,
const std::locale & = std::locale());
template<typename SequenceSequenceT, typename CollectionT,
typename PredicateT>
SequenceSequenceT &
split(SequenceSequenceT &, CollectionT &, PredicateT,
token_compress_mode_type = token_compress_off);
}
}Function template find_all3boost::algorithm::find_allFind all algorithm. template<typename SequenceSequenceT, typename Collection1T,
typename Collection2T>
SequenceSequenceT &
find_all(SequenceSequenceT & Result, Collection1T & Input,
const Collection2T & Search);DescriptionThis algorithm finds all occurrences of the search string in the input.Each part is copied and added as a new element to the output container. Thus the result container must be able to hold copies of the matches (in a compatible structure like std::string) or a reference to it (e.g. using the iterator range class). Examples of such a container are std::vector<std::string> or std::list<boost::iterator_range<std::string::iterator>>ParametersInputA container which will be searched. ResultA container that can hold copies of references to the substrings SearchA substring to be searched for. ReturnsA reference the resultNotesPrior content of the result will be overwritten.This function provides the strong exception-safety guarantee Function template ifind_all3boost::algorithm::ifind_allFind all algorithm ( case insensitive ). template<typename SequenceSequenceT, typename Collection1T,
typename Collection2T>
SequenceSequenceT &
ifind_all(SequenceSequenceT & Result, Collection1T & Input,
const Collection2T & Search,
const std::locale & Loc = std::locale());DescriptionThis algorithm finds all occurrences of the search string in the input. Each part is copied and added as a new element to the output container. Thus the result container must be able to hold copies of the matches (in a compatible structure like std::string) or a reference to it (e.g. using the iterator range class). Examples of such a container are std::vector<std::string> or std::list<boost::iterator_range<std::string::iterator>>Searching is case insensitive.ParametersInputA container which will be searched. LocA locale used for case insensitive comparison ResultA container that can hold copies of references to the substrings SearchA substring to be searched for. ReturnsA reference the resultNotesPrior content of the result will be overwritten.This function provides the strong exception-safety guarantee Function template split3boost::algorithm::splitSplit algorithm. template<typename SequenceSequenceT, typename CollectionT,
typename PredicateT>
SequenceSequenceT &
split(SequenceSequenceT & Result, CollectionT & Input, PredicateT Pred,
token_compress_mode_type eCompress = token_compress_off);DescriptionTokenize expression. This function is equivalent to C strtok. Input sequence is split into tokens, separated by separators. Separators are given by means of the predicate.Each part is copied and added as a new element to the output container. Thus the result container must be able to hold copies of the matches (in a compatible structure like std::string) or a reference to it (e.g. using the iterator range class). Examples of such a container are std::vector<std::string> or std::list<boost::iterator_range<std::string::iterator>>ParametersInputA container which will be searched. PredA predicate to identify separators. This predicate is supposed to return true if a given element is a separator. ResultA container that can hold copies of references to the substrings eCompressIf eCompress argument is set to token_compress_on, adjacent separators are merged together. Otherwise, every two separators delimit a token. ReturnsA reference the resultNotesPrior content of the result will be overwritten.This function provides the strong exception-safety guarantee Header <<ulink url="../../boost/algorithm/string/std_containers_traits.hpp">boost/algorithm/string/std_containers_traits.hpp</ulink>>This file includes sequence traits for stl containers.Header <<ulink url="../../boost/algorithm/string.hpp">boost/algorithm/string.hpp</ulink>>Cumulative include for string_algo libraryHeader <<ulink url="../../boost/algorithm/string_regex.hpp">boost/algorithm/string_regex.hpp</ulink>>Cumulative include for string_algo library. In addtion to string.hpp contains also regex-related stuff.Header <<ulink url="../../boost/algorithm/string/trim.hpp">boost/algorithm/string/trim.hpp</ulink>>Defines trim algorithms. Trim algorithms are used to remove trailing and leading spaces from a sequence (string). Space is recognized using given locales.Parametric (_if ) variants use a predicate (functor) to select which characters are to be trimmed.. Functions take a selection predicate as a parameter, which is used to determine whether a character is a space. Common predicates are provided in classification.hpp header.namespace boost {
namespace algorithm {
template<typename OutputIteratorT, typename CollectionT,
typename PredicateT>
OutputIteratorT
trim_left_copy_if(OutputIteratorT, const CollectionT &, PredicateT);
template<typename SequenceT, typename PredicateT>
SequenceT trim_left_copy_if(const SequenceT &, PredicateT);
template<typename SequenceT>
SequenceT trim_left_copy(const SequenceT &,
const std::locale & = std::locale());
template<typename SequenceT, typename PredicateT>
void trim_left_if(SequenceT &, PredicateT);
template<typename SequenceT>
void trim_left(SequenceT &, const std::locale & = std::locale());
template<typename OutputIteratorT, typename CollectionT,
typename PredicateT>
OutputIteratorT
trim_right_copy_if(OutputIteratorT, const CollectionT &, PredicateT);
template<typename SequenceT, typename PredicateT>
SequenceT trim_right_copy_if(const SequenceT &, PredicateT);
template<typename SequenceT>
SequenceT trim_right_copy(const SequenceT &,
const std::locale & = std::locale());
template<typename SequenceT, typename PredicateT>
void trim_right_if(SequenceT &, PredicateT);
template<typename SequenceT>
void trim_right(SequenceT &, const std::locale & = std::locale());
template<typename OutputIteratorT, typename CollectionT,
typename PredicateT>
OutputIteratorT
trim_copy_if(OutputIteratorT, const CollectionT &, PredicateT);
template<typename SequenceT, typename PredicateT>
SequenceT trim_copy_if(const SequenceT &, PredicateT);
template<typename SequenceT>
SequenceT trim_copy(const SequenceT &,
const std::locale & = std::locale());
template<typename SequenceT, typename PredicateT>
void trim_if(SequenceT &, PredicateT);
template<typename SequenceT>
void trim(SequenceT &, const std::locale & = std::locale());
}
}Function trim_left_copy_if3boost::algorithm::trim_left_copy_ifLeft trim - parametric. template<typename OutputIteratorT, typename CollectionT, typename PredicateT>
OutputIteratorT
trim_left_copy_if(OutputIteratorT Output, const CollectionT & Input,
PredicateT IsSpace);
template<typename SequenceT, typename PredicateT>
SequenceT trim_left_copy_if(const SequenceT & Input, PredicateT IsSpace);DescriptionRemove all leading spaces from the input. The supplied predicate is used to determine which characters are considered spaces. The result is a trimmed copy of the input. It is returned as a sequence or copied to the output iteratorParametersInputAn input collection IsSpaceAn unary predicate identifying spaces OutputAn output iterator to which the result will be copied ReturnsAn output iterator pointing just after the last inserted character or a copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template trim_left_copy3boost::algorithm::trim_left_copyLeft trim - parametric. template<typename SequenceT>
SequenceT trim_left_copy(const SequenceT & Input,
const std::locale & Loc = std::locale());DescriptionRemove all leading spaces from the input. The result is a trimmed copy of the input.ParametersInputAn input sequence Loca locale used for 'space' classification ReturnsA trimmed copy of the inputNotesThis function provides the strong exception-safety guarantee Function template trim_left_if3boost::algorithm::trim_left_ifLeft trim. template<typename SequenceT, typename PredicateT>
void trim_left_if(SequenceT & Input, PredicateT IsSpace);DescriptionRemove all leading spaces from the input. The supplied predicate is used to determine which characters are considered spaces. The input sequence is modified in-place.ParametersInputAn input sequence IsSpaceAn unary predicate identifying spaces Function template trim_left3boost::algorithm::trim_leftLeft trim. template<typename SequenceT>
void trim_left(SequenceT & Input, const std::locale & Loc = std::locale());DescriptionRemove all leading spaces from the input. The Input sequence is modified in-place.ParametersInputAn input sequence LocA locale used for 'space' classification Function trim_right_copy_if3boost::algorithm::trim_right_copy_ifRight trim - parametric. template<typename OutputIteratorT, typename CollectionT, typename PredicateT>
OutputIteratorT
trim_right_copy_if(OutputIteratorT Output, const CollectionT & Input,
PredicateT IsSpace);
template<typename SequenceT, typename PredicateT>
SequenceT trim_right_copy_if(const SequenceT & Input, PredicateT IsSpace);DescriptionRemove all trailing spaces from the input. The supplied predicate is used to determine which characters are considered spaces. The result is a trimmed copy of the input. It is returned as a sequence or copied to the output iteratorParametersInputAn input collection IsSpaceAn unary predicate identifying spaces OutputAn output iterator to which the result will be copied ReturnsAn output iterator pointing just after the last inserted character or a copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template trim_right_copy3boost::algorithm::trim_right_copyRight trim. template<typename SequenceT>
SequenceT trim_right_copy(const SequenceT & Input,
const std::locale & Loc = std::locale());DescriptionRemove all trailing spaces from the input. The result is a trimmed copy of the inputParametersInputAn input sequence LocA locale used for 'space' classification ReturnsA trimmed copy of the inputNotesThis function provides the strong exception-safety guarantee Function template trim_right_if3boost::algorithm::trim_right_ifRight trim - parametric. template<typename SequenceT, typename PredicateT>
void trim_right_if(SequenceT & Input, PredicateT IsSpace);DescriptionRemove all trailing spaces from the input. The supplied predicate is used to determine which characters are considered spaces. The input sequence is modified in-place.ParametersInputAn input sequence IsSpaceAn unary predicate identifying spaces Function template trim_right3boost::algorithm::trim_rightRight trim. template<typename SequenceT>
void trim_right(SequenceT & Input, const std::locale & Loc = std::locale());DescriptionRemove all trailing spaces from the input. The input sequence is modified in-place.ParametersInputAn input sequence LocA locale used for 'space' classification Function trim_copy_if3boost::algorithm::trim_copy_ifTrim - parametric. template<typename OutputIteratorT, typename CollectionT, typename PredicateT>
OutputIteratorT
trim_copy_if(OutputIteratorT Output, const CollectionT & Input,
PredicateT IsSpace);
template<typename SequenceT, typename PredicateT>
SequenceT trim_copy_if(const SequenceT & Input, PredicateT IsSpace);DescriptionRemove all trailing and leading spaces from the input. The supplied predicate is used to determine which characters are considered spaces. The result is a trimmed copy of the input. It is returned as a sequence or copied to the output iteratorParametersInputAn input collection IsSpaceAn unary predicate identifying spaces OutputAn output iterator to which the result will be copied ReturnsAn output iterator pointing just after the last inserted character or a copy of the inputNotesThe second variant of this function provides the strong exception-safety guarantee Function template trim_copy3boost::algorithm::trim_copyTrim. template<typename SequenceT>
SequenceT trim_copy(const SequenceT & Input,
const std::locale & Loc = std::locale());DescriptionRemove all leading and trailing spaces from the input. The result is a trimmed copy of the inputParametersInputAn input sequence LocA locale used for 'space' classification ReturnsA trimmed copy of the inputNotesThis function provides the strong exception-safety guarantee Function template trim_if3boost::algorithm::trim_ifTrim. template<typename SequenceT, typename PredicateT>
void trim_if(SequenceT & Input, PredicateT IsSpace);DescriptionRemove all leading and trailing spaces from the input. The supplied predicate is used to determine which characters are considered spaces. The input sequence is modified in-place.ParametersInputAn input sequence IsSpaceAn unary predicate identifying spaces Function template trim3boost::algorithm::trimTrim. template<typename SequenceT>
void trim(SequenceT & Input, const std::locale & Loc = std::locale());DescriptionRemove all leading and trailing spaces from the input. The input sequence is modified in-place.ParametersInputAn input sequence LocA locale used for 'space' classification RationaleLocales
Locales have a very close relation to string processing. They contain information about
the character sets and are used, for example, to change the case of characters and
to classify the characters.
C++ allows to work with multiple different instances of locales at once. If an algorithm
manipulates some data in a way that requires the usage of locales, there must be a way
to specify them. However, one instance of locales is sufficient for most of the applications,
and for a user it could be very tedious to specify which locales to use at every place
where it is needed.
Fortunately, the C++ standard allows to specify the global locales (using static member
function std:locale::global()). When instantiating an
std::locale class without explicit information, the instance will
be initialized with the global locale. This implies, that if an algorithm needs a locale,
it should have an std::locale parameter defaulting to std::locale().
If a user needs to specify locales explicitly, she can do so. Otherwise the global
locales are used.
Regular Expressions
Regular expressions are an essential part of text processing. For this reason, the library
also provides regex variants of some algorithms. The library does not attempt to replace
Boost.Regex; it merely wraps its functionality in a new interface.
As a part of this library, regex algorithms integrate smoothly with other components, which
brings additional value.
EnvironmentBuild
The whole library is provided in headers. Regex variants of some algorithms,
however, are dependent on the Boost.Regex library. All such algorithms are
separated in boost/algorithm/string_regex.hpp.
If this header is used, the application must be linked with the Boost.Regex
library.
Examples
Examples showing the basic usage of the library can be found in the libs/algorithm/string/example
directory. There is a separate file for the each part of the library. Please follow the boost
build guidelines to build examples using the bjam. To successfully build regex examples
the Boost.Regex library is required.
Tests
A full set of test cases for the library is located in the libs/algorithm/string/test directory.
The test cases can be executed using the boost build system. For the tests of regular
expression variants of algorithms, the Boost.Regex library is required.
Portability
The library has been successfully compiled and tested with the following compilers:
Microsoft Visual C++ 7.0Microsoft Visual C++ 7.1GCC 3.2GCC 3.3.1
See Boost regression tables
for additional info for a particular compiler.
There are known limitation on platforms not supporting partial template specialization.
Library depends on correctly implemented std::iterator_traits class.
If a standard library provided with compiler is broken, the String Algorithm Library
cannot function properly. Usually it implies that primitive pointer iterators are not
working with the library functions.
CreditsAcknowledgments
The author would like to thank everybody who gave suggestions and comments. Especially valuable
were the contributions of Thorsten Ottosen, Jeff Garland and the other boost members who participated
in the review process, namely David Abrahams, Daniel Frey, Beman Dawes, John Maddock, David B.Held, Pavel Vozenilek
and many other.
Additional thanks go to Stefan Slapeta and Toon Knapen, who have been very resourceful in solving various
portability issues.
WilliamE.Kempf200120022003William E. KempfPermission to use, copy, modify, distribute and sell this
software and its documentation for any purpose is hereby granted
without fee, provided that the above copyright notice appear in all
copies and that both that copyright notice and this permission notice
appear in supporting documentation. William E. Kempf makes no
representations about the suitability of this software for any purpose.
It is provided "as is" without express or implied warranty.<emphasis role="bold">Boost.Threads</emphasis>OverviewIntroductionBoost.Threads allows C++ programs to execute as multiple,
asynchronous, independent threads-of-execution. Each thread has its own
machine state including program instruction counter and registers. Programs
which execute as multiple threads are called multithreaded programs to
distinguish them from traditional single-threaded programs. The glossary gives a more complete description
of the multithreading execution environment.Multithreading provides several advantages:
Programs which would otherwise block waiting for some external
event can continue to respond if the blocking operation is placed in a
separate thread. Multithreading is usually an absolute requirement for
these programs.Well-designed multithreaded programs may execute faster than
single-threaded programs, particularly on multiprocessor hardware.
Note, however, that poorly-designed multithreaded programs are often
slower than single-threaded programs.Some program designs may be easier to formulate using a
multithreaded approach. After all, the real world is
asynchronous!DangersGeneral considerationsBeyond the errors which can occur in single-threaded programs,
multithreaded programs are subject to additional errors:
Race
conditionsDeadlock
(sometimes called "deadly embrace")Priority
failures (priority inversion, infinite overtaking, starvation,
etc.)Every multithreaded program must be designed carefully to avoid these
errors. These aren't rare or exotic failures - they are virtually guaranteed
to occur unless multithreaded code is designed to avoid them. Priority
failures are somewhat less common, but are nonetheless serious.The Boost.Threads design
attempts to minimize these errors, but they will still occur unless the
programmer proactively designs to avoid them.Please also see
for additional, implementation-specific considerations.Testing and debugging considerationsMultithreaded programs are non-deterministic. In other words, the
same program with the same input data may follow different execution
paths each time it is invoked. That can make testing and debugging a
nightmare:
Failures are often not repeatable.Probe effect causes debuggers to produce very different results
from non-debug uses.Debuggers require special support to show thread state.Tests on a single processor system may give no indication of
serious errors which would appear on multiprocessor systems, and visa
versa. Thus test cases should include a varying number of
processors.For programs which create a varying number of threads according
to workload, tests which don't span the full range of possibilities
may miss serious errors.Getting a head startAlthough it might appear that multithreaded programs are inherently
unreliable, many reliable multithreaded programs do exist. Multithreading
techniques are known which lead to reliable programs.Design patterns for reliable multithreaded programs, including the
important monitor pattern, are presented in
Pattern-Oriented Software Architecture Volume 2 - Patterns for
Concurrent and Networked Objects. Many important multithreading programming
considerations (independent of threading library) are discussed in
Programming with POSIX Threads.Doing some reading before attempting multithreaded designs will
give you a head start toward reliable multithreaded programs.C++ Standard Library usage in multithreaded programsRuntime librariesWarning: Multithreaded programs such as
those using Boost.Threads must link to thread-safe versions of
all runtime libraries used by the program, including the runtime library
for the C++ Standard Library. Failure to do so will cause race conditions to occur
when multiple threads simultaneously execute runtime library functions for
new, delete, or other language features which
imply shared state.Potentially non-thread-safe functionsCertain C++ Standard Library functions inherited from C are
particular problems because they hold internal state between
calls:
randstrtokasctimectimegmtimelocaltimeIt is possible to write thread-safe implementations of these by
using thread specific storage (see
boost::thread_specific_ptr), and several C++
compiler vendors do just that. The technique is well-know and is explained
in .But at least one vendor (HP-UX) does not provide thread-safe
implementations of the above functions in their otherwise thread-safe
runtime library. Instead they provide replacement functions with
different names and arguments.Recommendation: For the most
portable, yet thread-safe code, use Boost replacements for the problem
functions. See the Boost Random Number Library
and Boost Tokenizer Library.Common guarantees for all <emphasis role="bold">Boost.Threads</emphasis> componentsExceptionsBoost.Threads destructors never
throw exceptions. Unless otherwise specified, other
Boost.Threads functions that do not have
an exception-specification may throw implementation-defined
exceptions.In particular, Boost.Threads
reports failure to allocate storage by throwing an exception of type
std::bad_alloc or a class derived from
std::bad_alloc, failure to obtain thread resources other than
memory by throwing an exception of type
boost::thread_resource_error, and certain lock
related failures by throwing an exception of type
boost::lock_error.Rationale: Follows the C++ Standard
Library practice of allowing all functions except destructors or other
specified functions to throw exceptions on errors.NonCopyable requirementBoost.Threads classes documented as
meeting the NonCopyable requirement disallow copy construction and copy
assignment. For the sake of exposition, the synopsis of such classes show
private derivation from boost::noncopyable. Users
should not depend on this derivation, however, as implementations are free
to meet the NonCopyable requirement in other ways.DesignWith client/server and three-tier architectures becoming common place
in today's world, it's becoming increasingly important for programs to be
able to handle parallel processing. Modern day operating systems usually
provide some support for this through native thread APIs. Unfortunately,
writing portable code that makes use of parallel processing in C++ is made
very difficult by a lack of a standard interface for these native APIs.
Further, these APIs are almost universally C APIs and fail to take
advantage of C++'s strengths, or to address concepts unique to C++, such as
exceptions.The Boost.Threads library is an attempt to define a portable interface
for writing parallel processes in C++.GoalsThe Boost.Threads library has several goals that should help to set
it apart from other solutions. These goals are listed in order of precedence
with full descriptions below.
PortabilityBoost.Threads was designed to be highly portable. The goal is
for the interface to be easily implemented on any platform that
supports threads, and possibly even on platforms without native thread
support.SafetyBoost.Threads was designed to be as safe as possible. Writing
thread-safe
code is very difficult and successful libraries must strive to
insulate the programmer from dangerous constructs as much as
possible. This is accomplished in several ways:
C++ language features are used to make correct usage easy
(if possible) and error-prone usage impossible or at least more
difficult. For example, see the Mutex and Lock designs, and note
how they interact.Certain traditional concurrent programming features are
considered so error-prone that they are not provided at all. For
example, see .Dangerous features, or features which may be misused, are
identified as such in the documentation to make users aware of
potential pitfalls.FlexibilityBoost.Threads was designed to be flexible. This goal is often
at odds with safety. When functionality might be
compromised by the desire to keep the interface safe, Boost.Threads
has been designed to provide the functionality, but to make it's use
prohibitive for general use. In other words, the interfaces have been
designed such that it's usually obvious when something is unsafe, and
the documentation is written to explain why.EfficiencyBoost.Threads was designed to be as efficient as
possible. When building a library on top of another library there is
always a danger that the result will be so much slower than the
"native" API that programmers are inclined to ignore the higher level
API. Boost.Threads was designed to minimize the chances of this
occurring. The interfaces have been crafted to allow an implementation
the greatest chance of being as efficient as possible. This goal is
often at odds with the goal for safety. Every
effort was made to ensure efficient implementations, but when in
conflict safety has always taken
precedence.Iterative PhasesAnother goal of Boost.Threads was to take a dynamic, iterative
approach in its development. The computing industry is still exploring the
concepts of parallel programming. Most thread libraries supply only simple
primitive concepts for thread synchronization. These concepts are very
simple, but it is very difficult to use them safely or to provide formal
proofs for constructs built on top of them. There has been a lot of research
into other concepts, such as in "Communicating Sequential Processes."
Boost.Threads was designed in iterative steps, with each step providing
the building blocks necessary for the next step and giving the researcher
the tools necessary to explore new concepts in a portable manner.Given the goal of following a dynamic, iterative approach
Boost.Threads shall go through several growth cycles. Each phase in its
development shall be roughly documented here.Phase 1, Synchronization PrimitivesBoost is all about providing high quality libraries with
implementations for many platforms. Unfortunately, there's a big problem
faced by developers wishing to supply such high quality libraries, namely
thread-safety. The C++ standard doesn't address threads at all, but real
world programs often make use of native threading support. A portable
library that doesn't address the issue of thread-safety is therefore not
much help to a programmer who wants to use the library in his multithreaded
application. So there's a very great need for portable primitives that will
allow the library developer to create thread-safe
implementations. This need far out weighs the need for portable methods to
create and manage threads.Because of this need, the first phase of Boost.Threads focuses
solely on providing portable primitive concepts for thread
synchronization. Types provided in this phase include the
boost::mutex,
boost::try_mutex,
boost::timed_mutex,
boost::recursive_mutex,
boost::recursive_try_mutex,
boost::recursive_timed_mutex, and
boost::lock_error. These are considered the "core"
synchronization primitives, though there are others that will be added in
later phases.Phase 2, Thread Management and Thread Specific StorageThis phase addresses the creation and management of threads and
provides a mechanism for thread specific storage (data associated with a
thread instance). Thread management is a tricky issue in C++, so this
phase addresses only the basic needs of multithreaded program. Later
phases are likely to add additional functionality in this area. This
phase of Boost.Threads adds the boost::thread and
boost::thread_specific_ptr types. With these
additions the Boost.Threads library can be considered minimal but
complete.The Next PhaseThe next phase will address more advanced synchronization concepts,
such as read/write mutexes and barriers.ConceptsBoost.Threads currently supports two types of mutex concepts:
ordinary Mutexes,
which allow only one thread at a time to access a resource, and
Read/Write Mutexes,
which allow only one thread at a time to access a resource when it is
being modified (the "Write" part of Read/Write), but allows multiple threads
to access a resource when it is only being referenced (the "Read" part of
Read/Write).MutexesCertain changes to the mutexes and lock concepts are
currently under discussion. In particular, the combination of
the multiple lock concepts into a single lock concept
is likely, and the combination of the multiple mutex
concepts into a single mutex concept is also possible.A mutex (short for mutual-exclusion) object is used to serialize
access to a resource shared between multiple threads. The
Mutex concept, with
TryMutex and
TimedMutex refinements,
formalize the requirements. A model that implements Mutex and its
refinements has two states: locked and
unlocked. Before using a shared resource, a
thread locks a Boost.Threads mutex object
(an object whose type is a model of
Mutex or one of it's
refinements), ensuring
thread-safe access to
the shared resource. When use of the shared resource is complete, the thread
unlocks the mutex object, allowing another thread to acquire the lock and
use the shared resource.Traditional C thread APIs, like POSIX threads or the Windows thread
APIs, expose functions to lock and unlock a mutex object. This is dangerous
since it's easy to forget to unlock a locked mutex. When the flow of control
is complex, with multiple return points, the likelihood of forgetting to
unlock a mutex object becomes even greater. When exceptions are thrown,
it becomes nearly impossible to ensure that the mutex object is unlocked
properly when using these traditional API's. The result is
deadlock.Many C++ threading libraries use a pattern known as Scoped
Locking to free the programmer from
the need to explicitly lock and unlock mutex objects. With this pattern, a
Lock concept is employed where
the lock object's constructor locks the associated mutex object and the
destructor automatically does the unlocking. The
Boost.Threads library takes this pattern to
the extreme in that Lock concepts are the only way to lock and unlock a
mutex object: lock and unlock functions are not exposed by any
Boost.Threads mutex objects. This helps to
ensure safe usage patterns, especially when code throws exceptions.Locking StrategiesEvery mutex object follows one of several locking strategies. These
strategies define the semantics for the locking operation when the calling
thread already owns a lock on the mutex object.Recursive Locking StrategyWith a recursive locking strategy, when a thread attempts to acquire
a lock on the mutex object for which it already owns a lock, the operation
is successful. Note the distinction between a thread, which may have
multiple locks outstanding on a recursive mutex object, and a lock object,
which even for a recursive mutex object cannot have any of its lock
functions called multiple times without first calling unlock.Internally a lock count is maintained and the owning thread must
unlock the mutex object the same number of times that it locked it before
the mutex object's state returns to unlocked. Since mutex objects in
Boost.Threads expose locking
functionality only through lock concepts, a thread will always unlock a
mutex object the same number of times that it locked it. This helps to
eliminate a whole set of errors typically found in traditional C style
thread APIs.Classes boost::recursive_mutex,
boost::recursive_try_mutex and
boost::recursive_timed_mutex use this locking
strategy.Checked Locking StrategyWith a checked locking strategy, when a thread attempts to acquire a
lock on the mutex object for which the thread already owns a lock, the
operation will fail with some sort of error indication. Further, attempts
by a thread to unlock a mutex object that was not locked by the thread
will also return some sort of error indication. In
Boost.Threads, an exception of type
boost::lock_error
would be thrown in these cases.Boost.Threads does not currently
provide any mutex objects that use this strategy.Unchecked Locking StrategyWith an unchecked locking strategy, when a thread attempts to acquire
a lock on a mutex object for which the thread already owns a lock the
operation will
deadlock. In general
this locking strategy is less safe than a checked or recursive strategy,
but it's also a faster strategy and so is employed by many libraries.Boost.Threads does not currently
provide any mutex objects that use this strategy.Unspecified Locking StrategyWith an unspecified locking strategy, when a thread attempts to
acquire a lock on a mutex object for which the thread already owns a lock
the operation results in
undefined behavior.
In general a mutex object with an unspecified locking strategy is
unsafe, and it requires programmer discipline to use the mutex object
properly. However, this strategy allows an implementation to be as fast as
possible with no restrictions on its implementation. This is especially
true for portable implementations that wrap the native threading support
of a platform. For this reason, the classes
boost::mutex,
boost::try_mutex and
boost::timed_mutex use this locking strategy
despite the lack of safety.Scheduling PoliciesEvery mutex object follows one of several scheduling policies. These
policies define the semantics when the mutex object is unlocked and there is
more than one thread waiting to acquire a lock. In other words, the policy
defines which waiting thread shall acquire the lock.FIFO Scheduling PolicyWith a FIFO ("First In First Out") scheduling policy, threads waiting
for the lock will acquire it in a first-come-first-served order.
This can help prevent a high priority thread from starving lower priority
threads that are also waiting on the mutex object's lock.Priority Driven PolicyWith a Priority Driven scheduling policy, the thread with the
highest priority acquires the lock. Note that this means that low-priority
threads may never acquire the lock if the mutex object has high contention
and there is always at least one high-priority thread waiting. This is
known as thread starvation. When multiple threads of the same priority are
waiting on the mutex object's lock one of the other scheduling priorities
will determine which thread shall acquire the lock.Unspecified PolicyThe mutex object does not specify a scheduling policy. In order to
ensure portability, all Boost.Threads
mutex objects use an unspecified scheduling policy.Mutex ConceptsMutex ConceptA Mutex object has two states: locked and unlocked. Mutex object
state can only be determined by a lock object meeting the
appropriate lock concept requirements
and constructed for the Mutex object.A Mutex is
NonCopyable.For a Mutex type M
and an object m of that type,
the following expressions must be well-formed
and have the indicated effects.
Mutex ExpressionsExpressionEffectsM m;Constructs a mutex object m.Postcondition: m is unlocked.(&m)->~M();Precondition: m is unlocked. Destroys a mutex object
m.M::scoped_lockA model of
ScopedLock
TryMutex ConceptA TryMutex is a refinement of
Mutex.
For a TryMutex type M
and an object m of that type,
the following expressions must be well-formed
and have the indicated effects.
TryMutex ExpressionsExpressionEffectsM::scoped_try_lockA model of
ScopedTryLock
TimedMutex ConceptA TimedMutex is a refinement of
TryMutex.
For a TimedMutex type M
and an object m of that type,
the following expressions must be well-formed
and have the indicated effects.
TimedMutex ExpressionsExpressionEffectsM::scoped_timed_lockA model of
ScopedTimedLock
Mutex ModelsBoost.Threads currently supplies six models of
Mutex
and its refinements.
Lock ConceptsA lock object provides a safe means for locking and unlocking a mutex
object (an object whose type is a model of Mutex or one of its refinements). In
other words they are an implementation of the Scoped
Locking pattern. The ScopedLock,
ScopedTryLock, and
ScopedTimedLock
concepts formalize the requirements.Lock objects are constructed with a reference to a mutex object and
typically acquire ownership of the mutex object by setting its state to
locked. They also ensure ownership is relinquished in the destructor. Lock
objects also expose functions to query the lock status and to manually lock
and unlock the mutex object.Lock objects are meant to be short lived, expected to be used at block
scope only. The lock objects are not thread-safe. Lock objects must
maintain state to indicate whether or not they've been locked and this state
is not protected by any synchronization concepts. For this reason a lock
object should never be shared between multiple threads.Lock ConceptFor a Lock type L
and an object lk
and const object clk of that type,
the following expressions must be well-formed
and have the indicated effects.
Lock ExpressionsExpressionEffects(&lk)->~L();if (locked()) unlock();(&clk)->operator const void*()Returns type void*, non-zero if the associated mutex
object has been locked by clk, otherwise 0.clk.locked()Returns a bool, (&clk)->operator
const void*() != 0lk.lock()Throws boost::lock_error
if locked().If the associated mutex object is
already locked by some other thread, places the current thread in the
Blocked state until
the associated mutex is unlocked, after which the current thread
is placed in the Ready state,
eventually to be returned to the Running state. If
the associated mutex object is already locked by the same thread
the behavior is dependent on the locking
strategy of the associated mutex object.Postcondition: locked() == truelk.unlock()Throws boost::lock_error
if !locked().Unlocks the associated mutex.Postcondition: !locked()
ScopedLock ConceptA ScopedLock is a refinement of Lock.
For a ScopedLock type L
and an object lk of that type,
and an object m of a type meeting the
Mutex requirements,
and an object b of type bool,
the following expressions must be well-formed
and have the indicated effects.
ScopedLock ExpressionsExpressionEffectsL lk(m);Constructs an object lk, and associates mutex
object m with it, then calls
lock()L lk(m,b);Constructs an object lk, and associates mutex
object m with it, then if b, calls
lock()
TryLock ConceptA TryLock is a refinement of Lock.
For a TryLock type L
and an object lk of that type,
the following expressions must be well-formed
and have the indicated effects.
TryLock ExpressionsExpressionEffectslk.try_lock()Throws boost::lock_error
if locked().Makes a
non-blocking attempt to lock the associated mutex object,
returning true if the lock attempt is successful,
otherwise false. If the associated mutex object is
already locked by the same thread the behavior is dependent on the
locking
strategy of the associated mutex object.
ScopedTryLock ConceptA ScopedTryLock is a refinement of TryLock.
For a ScopedTryLock type L
and an object lk of that type,
and an object m of a type meeting the
TryMutex requirements,
and an object b of type bool,
the following expressions must be well-formed
and have the indicated effects.
ScopedTryLock ExpressionsExpressionEffectsL lk(m);Constructs an object lk, and associates mutex
object m with it, then calls
try_lock()L lk(m,b);Constructs an object lk, and associates mutex
object m with it, then if b, calls
lock()
TimedLock ConceptA TimedLock is a refinement of TryLock.
For a TimedLock type L
and an object lk of that type,
and an object t of type boost::xtime,
the following expressions must be well-formed
and have the indicated effects.
TimedLock ExpressionsExpressionEffectslk.timed_lock(t)Throws boost::lock_error
if locked().Makes a blocking attempt
to lock the associated mutex object, and returns true
if successful within the specified time t, otherwise
false. If the associated mutex object is already
locked by the same thread the behavior is dependent on the locking
strategy of the associated mutex object.
ScopedTimedLock ConceptA ScopedTimedLock is a refinement of TimedLock.
For a ScopedTimedLock type L
and an object lk of that type,
and an object m of a type meeting the
TimedMutex requirements,
and an object b of type bool,
and an object t of type boost::xtime,
the following expressions must be well-formed
and have the indicated effects.
ScopedTimedLock ExpressionsExpressionEffectsL lk(m,t);Constructs an object lk, and associates mutex
object m with it, then calls
timed_lock(t)L lk(m,b);Constructs an object lk, and associates mutex
object m with it, then if b, calls
lock()
Lock ModelsBoost.Threads currently supplies twelve models of
Lock
and its refinements.
Read/Write MutexesSince the read/write mutex and related classes are new,
both interface and implementation are liable to change
in future releases of Boost.Threads.
The lock concepts and lock promotion and demotion in particular
are still under discussion and very likely to change.A read/write mutex (short for reader/writer mutual-exclusion) object
is used to serialize access to a resource shared between multiple
threads, where multiple "readers" can share simultaneous access, but
"writers" require exclusive access. The
ReadWriteMutex concept, with
TryReadWriteMutex and
TimedReadWriteMutex
refinements formalize the requirements. A model that implements
ReadWriteMutex and its refinements has three states:
read-locked,
write-locked, and
unlocked.
Before reading from a shared resource, a thread
read-locks
a Boost.Threads read/write mutex object
(an object whose type is a model of
ReadWriteMutex
or one of it's refinements), ensuring
thread-safe
access for reading from the shared resource. Before writing
to a shared resource, a thread
write-locks a Boost.Threads
read/write mutex object
(an object whose type is a model of
ReadWriteMutex
or one of it's refinements), ensuring
thread-safe
access for altering the shared resource. When use of the shared
resource is complete, the thread unlocks the mutex object,
allowing another thread to acquire the lock and use the shared
resource.Traditional C thread APIs that provide read/write mutex
primitives (like POSIX threads) expose functions to lock and unlock a
mutex object. This is dangerous since it's easy to forget to unlock a
locked mutex. When the flow of control is complex, with multiple
return points, the likelihood of forgetting to unlock a mutex object
becomes even greater. When exceptions are thrown, it becomes nearly
impossible to ensure that the mutex object is unlocked
properly when using these traditional API's. The result is
deadlock.Many C++ threading libraries use a pattern known as Scoped
Locking to free the
programmer from the need to explicitly lock and unlock
read/write mutex objects. With this pattern, a
Read/Write Lock
concept is employed where the lock object's constructor locks
the associated read/write mutex object
and the destructor automatically does the unlocking. The
Boost.Threads library takes this pattern to
the extreme in that
Read/Write Lock
concepts are the only way to lock and unlock a read/write mutex
object: lock and unlock functions are not exposed by any
Boost.Threads read/write mutex objects. This helps to
ensure safe usage patterns, especially when code throws exceptions.Locking StrategiesEvery read/write mutex object follows one of several locking
strategies. These strategies define the semantics for the locking
operation when the calling thread already owns a lock on the
read/write mutex object.Recursive Locking StrategyWith a recursive locking strategy, when a thread attempts
to acquire a lock on a read/write mutex object
for which it already owns a lock, the operation is successful,
except in the case where a thread holding a read-lock
attempts to obtain a write lock, in which case a
boost::lock_error exception will
be thrown. Note the distinction between a thread, which may have
multiple locks outstanding on a recursive read/write mutex object,
and a lock object, which even for a recursive read/write mutex
object cannot have any of its lock functions called multiple
times without first calling unlock.Lock Type HeldLock Type RequestedActionread-lockread-lockGrant the read-lock immediatelyread-lockwrite-lockIf this thread is the only holder of the read-lock,
grants the write lock immediately. Otherwise throws a
boost::lock_error exception.write-lockedread-lockGrants the (additional) read-lock immediately.write-lockedwrite-lock Grant the write-lock immediatelyInternally a lock count is maintained and the owning
thread must unlock the mutex object the same number of times
that it locked it before the mutex object's state returns
to unlocked. Since mutex objects in Boost.Threads expose
locking functionality only through lock concepts, a thread
will always unlock a mutex object the same number of times
that it locked it. This helps to eliminate a whole set of
errors typically found in traditional C style thread APIs.
Boost.Threads does not currently provide any read/write mutex objects
that use this strategy. A successful implementation of this locking strategy
may require
thread identification.
Checked Locking StrategyWith a checked locking strategy, when a thread attempts
to acquire a lock on the mutex object for which the thread
already owns a lock, the operation will fail with some sort of
error indication, except in the case of multiple read-lock
acquisition which is a normal operation for ANY ReadWriteMutex.
Further, attempts by a thread to unlock a mutex that was not
locked by the thread will also return some sort of error
indication. In Boost.Threads, an exception of type
boost::lock_error would be thrown in
these cases.Lock Type HeldLock Type RequestedActionread-lockread-lockGrant the read-lock immediatelyread-lockwrite-lockThrow boost::lock_errorwrite-lockedread-lockThrow boost::lock_errorwrite-lockedwrite-lock Throw boost::lock_errorBoost.Threads does not currently provide any read/write mutex objects
that use this strategy. A successful implementation of this locking strategy
may require
thread identification.
Unchecked Locking StrategyWith an unchecked locking strategy, when a thread
attempts to acquire a lock on the read/write mutex object
for which the thread already owns a lock, the operation
will deadlock.
In general this locking strategy is less safe than a checked
or recursive strategy, but it can be a faster strategy and so
is employed by many libraries.Lock Type HeldLock Type RequestedActionread-lockread-lockGrant the read-lock immediatelyread-lockwrite-lockDeadlockwrite-lockedread-lockDeadlockwrite-lockedwrite-lockDeadlockBoost.Threads does not currently provide any mutex
objects that use this strategy. For ReadWriteMutexes on
platforms that contain natively recursive synchronization
primitives, implementing a guaranteed-deadlock can actually
involve extra work, and would likely require
thread identification.
Unspecified Locking StrategyWith an unspecified locking strategy, when a thread
attempts to acquire a lock on a read/write mutex object for
which the thread already owns a lock, the operation results
in undefined behavior.
When a read/write mutex object has an unspecified locking
strategy the programmer must assume that the read/write mutex
object instead uses an unchecked strategy as the worse case,
although some platforms may exhibit a mix of unchecked and
recursive behavior.Lock Type HeldLock Type RequestedActionread-lockread-lockGrant the read-lock immediatelyread-lockwrite-lockUndefined, but generally deadlockwrite-lockedread-lockUndefined, but generally deadlockwrite-lockedwrite-lockUndefined, but generally deadlockIn general a read/write mutex object with an unspecified
locking strategy is unsafe, and it requires programmer discipline
to use the read/write mutex object properly. However, this strategy
allows an implementation to be as fast as possible with no restrictions
on its implementation. This is especially true for portable implementations
that wrap the native threading support of a platform. For this reason, the
classes
read_write_mutex,
try_read_write_mutex, and
timed_read_write_mutex
use this locking strategy despite the lack of safety.Thread IdentificationReadWriteMutexes can support specific Locking Strategies
(recursive and checked) which help to detect and protect against
self-deadlock. Self-deadlock can occur when a holder of a locked
ReadWriteMutex attempts to obtain another lock. Given an
implemention I which is susceptible to
self-deadlock but otherwise correct and efficient, a recursive or
checked implementation Ir or
Ic can use the same basic implementation,
but make special checks against self-deadlock by tracking the
identities of thread(s) currently holding locks. This approach
makes deadlock detection othrogonal to the basic ReadWriteMutex
implementaion.Alternatively, a different basic implementation for
ReadWriteMutex concepts,
I' (I-Prime) may exist which uses recursive
or checked versions of synchronization primitives to produce
a recursive or checked ReadWriteMutex while still providing
flexibility in terms of Scheduling Policies. Please refer to the Boost.Threadsread/write mutex concept
documentation for a discussion of locking strategies.
The read/write mutex supports only the
unspecified
locking strategy. ReadWriteMutexes are parameterized on a
Mutex type which they use to control write-locking
and access to internal state.Lock PromotionReadWriteMutexes can support lock promotion, where a
mutex which is in the read-locked state transitions to a
write-locked state without releasing the lock. Lock
promotion can be tricky to implement; for instance,
extra care must be taken to ensure that only one thread holding a
read-lock can block awaiting promotion at any given time. If
more than one read-lock holder is allowed to enter a blocked
state while waiting to be promoted, deadlock will result since
both threads will be waiting for the other to release their read-lock.
Currently, Boost.Threads supports lock promotion
through promote(), try_promote(),
and timed_promote() operations.Lock DemotionReadWriteMutexes can support lock demotion, where a
mutex which is in the write-locked state transitions to a
read-locked state without releasing the lock.
Since by definition only one thread at a time may hold
a write-lock, the problem with deadlock that can occur
during lock promotion is not a problem for lock
demotion.Currently, Boost.Threads supports lock demotion
through demote(), try_demote(),
and timed_demote() operations.Scheduling PoliciesEvery read/write mutex object follows one of several scheduling
policies. These policies define the semantics when the mutex object
is unlocked and there is more than one thread waiting to acquire a
lock. In other words, the policy defines which waiting thread shall
acquire the lock. For a read/write mutex, it is particularly important
to define the behavior when threads are requesting both read and
write access simultaneously. This will be referred to as "inter-class
scheduling" because it describes the scheduling between two
classes of threads (those waiting for a read lock and those
waiting for a write lock).For some types of inter-class scheduling, an "intra-class"
scheduling policy can also be defined that will describe the order
in which waiting threads of the same class (i.e., those
waiting for the same type of lock) will acquire the thread.
Inter-Class Scheduling PoliciesReaderPriorityWith ReaderPriority scheduling, any pending request for
a read-lock will have priority over a pending request for a
write-lock, irrespective of the current lock state of the
read/write mutex, and irrespective of the relative order
that the pending requests arrive.Current mutex stateRequest TypeActionunlockedread-lockGrant the read-lock immediatelyread-lockedread-lockGrant the additional read-lock immediately.write-lockedread-lockWait to acquire the lock until the thread
holding the write-lock releases its lock (or until
the specified time, if any). A
read-lock will be granted to all pending readers
before any other thread can acquire a write-lock.
TODO: try-lock, timed-lock.unlockedwrite-lockGrant the write-lock immediately, if and
only if there are no pending read-lock requests.
TODO: try-lock, timed-lock.read-lockedwrite-lock Wait to acquire the lock until all
threads holding read-locks release their locks
AND no requests
for read-locks exist. If other write-lock
requests exist, the lock is granted in accordance
with the intra-class scheduling policy.
TODO: try-lock, timed-lock.write-lockedwrite-lockWait to acquire the lock until the thread
holding the write-lock releases its lock
AND no requests
for read-locks exist. If other write-lock
requests exist, the lock is granted in accordance
with the intra-class scheduling policy.
TODO: try-lock, timed-lock.read-lockedpromoteTODOwrite-lockeddemoteTODOWriterPriorityWith WriterPriority scheduling, any pending request
for a write-lock will have priority over a pending request
for a read-lock, irrespective of the current lock state
of the read/write mutex, and irrespective of the relative
order that the pending requests arrive.Current mutex stateRequest TypeActionunlockedread-lockGrant the read-lock immediately.read-lockedread-lockGrant the additional read-lock immediately,
IF no outstanding
requests for a write-lock exist; otherwise TODO.
TODO: try-lock, timed-lock.write-lockedread-lock Wait to acquire the lock until the
thread holding the write-lock
releases its lock. The read lock will be granted
once no other outstanding write-lock requests
exist.
TODO: try-lock, timed-lock.unlockedwrite-lockGrant the write-lock immediately.read-lockedwrite-lockWait to acquire the lock until all
threads holding read-locks release their locks.
If other write-lock requests exist, the lock
is granted in accordance with the intra-class
scheduling policy. This request will be granted
before any new read-lock requests are granted.
TODO: try-lock, timed-lock.write-lockedwrite-lockWait to acquire the lock until the thread
holding the write-lock releases its lock. If
other write-lock requests exist, the lock is
granted in accordance with the intra-class
scheduling policy. This request will be granted
before any new read-lock requests are granted.
TODO: try-lock, timed-lock.read-lockedpromoteTODOwrite-lockeddemoteTODOAlternatingPriority/ManyReadsWith AlternatingPriority/ManyReads scheduling, reader
or writer starvation is avoided by alternatively granting read
or write access when pending requests exist for both types of
locks. Outstanding read-lock requests are treated as a group
when it is the "readers' turn"Current mutex stateRequest TypeActionunlockedread-lockGrant the read-lock immediately.read-lockedread-lockGrant the additional read-lock immediately,
IF no outstanding
requests for a write-lock exist. If outstanding
write-lock requests exist, this lock will not
be granted until at least one of the
write-locks is granted and released. If other
read-lock requests exist, all read-locks will be
granted as a group.
TODO: try-lock, timed-lock.write-lockedread-lock Wait to acquire the lock until the thread
holding the write-lock releases its lock. If other
outstanding write-lock requests exist, they will
have to wait until all current read-lock requests
are serviced.
TODO: try-lock, timed-lock.unlockedwrite-lockGrant the write-lock immediately.read-lockedwrite-lockWait to acquire the lock until all threads
holding read-locks release their locks.If other write-lock requests exist, this
lock will be granted to one of them in accordance
with the intra-class scheduling policy.TODO: try-lock, timed-lock.write-lockedwrite-lockWait to acquire the lock until the thread
holding the write-lock releases its lock. If
other outstanding read-lock requests exist, this
lock will not be granted until all of the
currently waiting read-locks are granted and
released. If other write-lock requests exist,
this lock will be granted in accordance with the
intra-class scheduling policy.
TODO: try-lock, timed-lock.read-lockedpromoteTODOwrite-lockeddemoteTODOAlternatingPriority/SingleReadWith AlternatingPriority/SingleRead scheduling, reader
or writer starvation is avoided by alternatively granting read
or write access when pending requests exist for both types of
locks. Outstanding read-lock requests are services one at a
time when it is the "readers' turn"Current mutex stateRequest TypeActionunlockedread-lockGrant the read-lock immediately.read-lockedread-lockGrant the additional read-lock immediately,
IF no outstanding
requests for a write-lock exist. If outstanding
write-lock requests exist, this lock will not
be granted until at least one of the write-locks
is granted and released.
TODO: try-lock, timed-lock.write-lockedread-lockWait to acquire the lock until the thread
holding the write-lock releases its lock.If other outstanding write-lock requests
exist, exactly one read-lock request will be
granted before the next write-lock is granted.
TODO: try-lock, timed-lock.unlockedwrite-lockGrant the write-lock immediately.read-lockedwrite-lockWait to acquire the lock until all
threads holding read-locks release their
locks.If other write-lock requests exist,
this lock will be granted to one of them
in accordance with the intra-class
scheduling policy.TODO: try-lock, timed-lock.write-lockedwrite-lockWait to acquire the lock until the
thread holding the write-lock releases its
lock. If other outstanding read-lock requests
exist, this lock can not be granted until
exactly one read-lock request is granted and
released. If other write-lock requests exist,
this lock will be granted in accordance with
the intra-class scheduling policy.
TODO: try-lock, timed-lock.read-lockedpromoteTODOwrite-lockeddemoteTODOIntra-Class Scheduling PoliciesPlease refer to
for a discussion of mutex scheduling policies, which are identical to
read/write mutex intra-class scheduling policies.For threads waiting to obtain write-locks, the read/write mutex
supports only the
Unspecified
intra-class scheduling policy. That is, given a set of threads
waiting for write-locks, the order, relative to one another, in
which they receive the write-lock is unspecified.For threads waiting to obtain read-locks, the read/write mutex
supports only the
Unspecified
intra-class scheduling policy. That is, given a set of threads
waiting for read-locks, the order, relative to one another, in
which they receive the read-lock is unspecified.Mutex ConceptsReadWriteMutex ConceptA ReadWriteMutex object has three states: read-locked,
write-locked, and unlocked. ReadWriteMutex object state can
only be determined by a lock object meeting the appropriate lock concept
requirements and constructed for the ReadWriteMutex object.A ReadWriteMutex is
NonCopyable.
For a ReadWriteMutex type M,
and an object m of that type,
the following expressions must be well-formed
and have the indicated effects.
ReadWriteMutex ExpressionsExpressionEffectsM m;Constructs a read/write mutex object m.
Post-condition: m is unlocked.(&m)->~M();Precondition: m is unlocked.
Destroys a read/write mutex object m.
M::scoped_read_write_lockA type meeting the
ScopedReadWriteLock
requirements. M::scoped_read_lockA type meeting the
ScopedLock
requirements. M::scoped_write_lockA type meeting the
ScopedLock
requirements.
TryReadWriteMutex ConceptA TryReadWriteMutex is a refinement of
ReadWriteMutex.
For a TryReadWriteMutex type M
and an object m of that type,
the following expressions must be well-formed
and have the indicated effects.
TryReadWriteMutex ExpressionsExpressionEffectsM::scoped_try_read_write_lockA type meeting the
ScopedTryReadWriteLock
requirements.M::scoped_try_read_lockA type meeting the
ScopedTryLock
requirements.M::scoped_try_write_lockA type meeting the
ScopedTryLock
requirements.
TimedReadWriteMutex ConceptA TimedReadWriteMutex is a refinement of
TryReadWriteMutex.
For a TimedReadWriteMutex type M
and an object m of that type
the following expressions must be well-formed
and have the indicated effects.
TimedReadWriteMutex ExpressionsExpressionEffectsM::scoped_timed_read_write_lockA type meeting the
ScopedTimedReadWriteLock
requirements.M::scoped_timed_read_lockA type meeting the
ScopedTimedLock
requirements.M::scoped_timed_write_lockA type meeting the
ScopedTimedLock
requirements.
Mutex ModelsBoost.Threads currently supplies three models of
ReadWriteMutex
and its refinements.
Lock ConceptsA read/write lock object provides a safe means for locking
and unlocking a read/write mutex object (an object whose type is
a model of
ReadWriteMutex
or one of its refinements). In other words they are an
implementation of the Scoped Locking pattern. The
ScopedReadWriteLock,
ScopedTryReadWriteLock, and
ScopedTimedReadWriteLock
concepts formalize the requirements.Read/write lock objects are constructed with a reference to a
read/write mutex object and typically acquire ownership of the
read/write mutex object by setting its state to locked. They also
ensure ownership is relinquished in the destructor. Lock objects
also expose functions to query the lock status and to manually lock
and unlock the read/write mutex object.Read/write lock objects are meant to be short lived, expected
to be used at block scope only. The read/write lock objects are not
thread-safe.
Read/write lock objects must maintain state to indicate whether or
not they've been locked and this state is not protected by any
synchronization concepts. For this reason a read/write lock object
should never be shared between multiple threads.ReadWriteLock ConceptFor a read/write lock type L
and an object lk
and const object clk of that type,
the following expressions must be well-formed
and have the indicated effects.
ReadWriteLock ExpressionsExpressionEffects(&lk)->~L();if (locked()) unlock();(&clk)->operator const void*()Returns type void*, non-zero if the associated read/write
mutex object has been either read-locked or write-locked by
clk, otherwise 0.clk.locked()Returns a bool, (&clk)->operator
const void*() != 0clk.state()Returns an enumeration constant of type read_write_lock_state:
read_write_lock_state::read_locked if the associated read/write mutex object has been
read-locked by clk, read_write_lock_state::write_locked if it
has been write-locked by clk, and read_write_lock_state::unlocked
if has not been locked by clk.clk.read_locked()Returns a bool, (&clk)->state() == read_write_lock_state::read_locked.clk.write_locked()Returns a bool, (&clk)->state() == read_write_lock_state::write_locked.lk.read_lock()Throws boost::lock_error
if locked().If the associated read/write mutex
object is already read-locked by some other
thread, the effect depends on the
inter-class scheduling policy
of the associated read/write mutex:
either immediately obtains an additional
read-lock on the associated read/write
mutex, or places the current thread in the
Blocked
state until the associated read/write mutex
is unlocked, after which the current thread
is placed in the
Ready
state, eventually to be returned to the
Running
state.If the associated read/write mutex
object is already write-locked by some other
thread, places the current thread in the
Blocked
state until the associated read/write mutex
is unlocked, after which the current thread
is placed in the
Ready
state, eventually to be returned to the
Running
state.If the associated read/write mutex
object is already locked by the same thread
the behavior is dependent on the
locking strategy
of the associated read/write mutex object.
Postcondition: state() == read_write_lock_state::read_lockedlk.write_lock()Throws boost::lock_error
if locked().If the associated read/write mutex
object is already locked by some other
thread, places the current thread in the
Blocked
state until the associated read/write mutex
is unlocked, after which the current thread
is placed in the
Ready
state, eventually to be returned to the
Running
state.If the associated read/write mutex
object is already locked by the same thread
the behavior is dependent on the
locking strategy
of the associated read/write mutex object.
Postcondition: state() == read_write_lock_state::write_lockedlk.demote()Throws boost::lock_error
if state() != read_write_lock_state::write_locked.Converts the lock held on the associated read/write mutex
object from a write-lock to a read-lock without releasing
the lock.Postcondition: state() == read_write_lock_state::read_lockedlk.promote()Throws boost::lock_error
if state() != read_write_lock_state::read_locked
or if the lock cannot be promoted because another lock
on the same mutex is already waiting to be promoted.Makes a blocking attempt to convert the lock held on the associated
read/write mutex object from a read-lock to a write-lock without releasing
the lock.lk.unlock()Throws boost::lock_error
if !locked().Unlocks the associated read/write mutex.Postcondition: !locked()
ScopedReadWriteLock ConceptA ScopedReadWriteLock is a refinement of
ReadWriteLock.
For a ScopedReadWriteLock type L
and an object lk of that type,
and an object m of a type meeting the
ReadWriteMutex requirements,
and an object s of type read_write_lock_state,
the following expressions must be well-formed
and have the indicated effects.
ScopedReadWriteLock ExpressionsExpressionEffectsL lk(m,s);Constructs an object lk and associates read/write mutex
object m with it, then: if s == read_write_lock_state::read_locked, calls
read_lock(); if s==read_write_lock_state::write_locked,
calls write_lock().
TryReadWriteLock ExpressionsA TryReadWriteLock is a refinement of
ReadWriteLock.
For a TryReadWriteLock type L
and an object lk of that type,
the following expressions must be well-formed
and have the indicated effects.
TryReadWriteLock ExpressionsExpressionEffectslk.try_read_lock()Throws boost::lock_error
if locked().Makes a non-blocking attempt to read-lock the associated read/write
mutex object, returning true if the attempt is successful,
otherwise false. If the associated read/write mutex object is
already locked by the same thread the behavior is dependent on the
locking
strategy of the associated read/write mutex object.lk.try_write_lock()Throws boost::lock_error
if locked().Makes a non-blocking attempt to write-lock the associated read/write
mutex object, returning true if the attempt is successful,
otherwise false. If the associated read/write mutex object is
already locked by the same thread the behavior is dependent on the
locking
strategy of the associated read/write mutex object.lk.try_demote()Throws boost::lock_error
if state() != read_write_lock_state::write_locked.Makes a non-blocking attempt to convert the lock held on the associated
read/write mutex object from a write-lock to a read-lock without releasing
the lock, returning true if the attempt is successful,
otherwise false.lk.try_promote()Throws boost::lock_error
if state() != read_write_lock_state::read_locked.Makes a non-blocking attempt to convert the lock held on the associated
read/write mutex object from a read-lock to a write-lock without releasing
the lock, returning true if the attempt is successful,
otherwise false.
ScopedTryReadWriteLock ExpressionsA ScopedTryReadWriteLock is a refinement of
TryReadWriteLock.
For a ScopedTryReadWriteLock type L
and an object lk of that type,
and an object m of a type meeting the
TryReadWriteMutex requirements,
and an object s of type read_write_lock_state,
and an object b of type blocking_mode,
the following expressions must be well-formed
and have the indicated effects.
ScopedTryReadWriteLock ExpressionsExpressionEffectsL lk(m,s,b);Constructs an object lk and associates read/write mutex
object m with it, then: if s == read_write_lock_state::read_locked, calls
read_lock() if b, otherwise try_read_lock();
if s==read_write_lock_state::write_locked, calls write_lock() if b,
otherwise try_write_lock.
TimedReadWriteLock ConceptA TimedReadWriteLock is a refinement of
TryReadWriteLock.
For a TimedReadWriteLock type L
and an object lk of that type,
and an object t of type boost::xtime,
the following expressions must be well-formed
and have the indicated effects.
TimedReadWriteLock ExpressionsExpressionEffectslk.timed_read_lock(t)Throws boost::lock_error
if locked().Makes a blocking attempt to read-lock the associated read/write mutex object,
and returns true if successful within the specified time t,
otherwise false. If the associated read/write mutex object is already
locked by the same thread the behavior is dependent on the locking
strategy of the associated read/write mutex object.lk.timed_write_lock(t)Throws boost::lock_error
if locked().Makes a blocking attempt to write-lock the associated read/write mutex object,
and returns true if successful within the specified time t,
otherwise false. If the associated read/write mutex object is already
locked by the same thread the behavior is dependent on the locking
strategy of the associated read/write mutex object.lk.timed_demote(t)Throws boost::lock_error
if state() != read_write_lock_state::write_locked.Makes a blocking attempt to convert the lock held on the associated
read/write mutex object from a write-lock to a read-lock without releasing
the lock, returning true if the attempt is successful
in the specified time t, otherwise false.lk.timed_promote(t)Throws boost::lock_error
if state() != read_write_lock_state::read_locked.Makes a blocking attempt to convert the lock held on the associated
read/write mutex object from a read-lock to a write-lock without releasing
the lock, returning true if the attempt is successful
in the specified time t, otherwise false.
ScopedTimedReadWriteLock ConceptA ScopedTimedReadWriteLock is a refinement of
TimedReadWriteLock.
For a ScopedTimedReadWriteLock type L
and an object lk of that type,
and an object m of a type meeting the
TimedReadWriteMutex requirements,
and an object s of type read_write_lock_state,
and an object t of type boost::xtime,
and an object b of type blocking_mode,
the following expressions must be well-formed and have the
indicated effects.
ScopedTimedReadWriteLock ExpressionsExpressionEffectsL lk(m,s,b);Constructs an object lk and associates read/write mutex
object m with it, then: if s == read_write_lock_state::read_locked, calls
read_lock() if b, otherwise try_read_lock();
if s==read_write_lock_state::write_locked, calls write_lock() if b,
otherwise try_write_lock.L lk(m,s,t);Constructs an object lk and associates read/write mutex
object m with it, then: if s == read_write_lock_state::read_locked, calls
timed_read_lock(t); if s==read_write_lock_state::write_locked,
calls timed_write_lock(t).
Lock ModelsBoost.Threads currently supplies six models of
ReadWriteLock
and its refinements.
RationaleThis page explains the rationale behind various design decisions in the
Boost.Threads library. Having the rationale documented here should explain
how we arrived at the current design as well as prevent future rehashing of
discussions and thought processes that have already occurred. It can also give
users a lot of insight into the design process required for this
library.Rationale for the Creation of <emphasis role="bold">Boost.Threads</emphasis>Processes often have a degree of "potential parallelism" and it can
often be more intuitive to design systems with this in mind. Further, these
parallel processes can result in more responsive programs. The benefits for
multithreaded programming are quite well known to most modern programmers,
yet the C++ language doesn't directly support this concept.Many platforms support multithreaded programming despite the fact that
the language doesn't support it. They do this through external libraries,
which are, unfortunately, platform specific. POSIX has tried to address this
problem through the standardization of a "pthread" library. However, this is
a standard only on POSIX platforms, so its portability is limited.Another problem with POSIX and other platform specific thread
libraries is that they are almost universally C based libraries. This leaves
several C++ specific issues unresolved, such as what happens when an
exception is thrown in a thread. Further, there are some C++ concepts, such
as destructors, that can make usage much easier than what's available in a C
library.What's truly needed is C++ language support for threads. However, the
C++ standards committee needs existing practice or a good proposal as a
starting point for adding this to the standard.The Boost.Threads library was developed to provide a C++ developer
with a portable interface for writing multithreaded programs on numerous
platforms. There's a hope that the library can be the basis for a more
detailed proposal for the C++ standards committee to consider for inclusion
in the next C++ standard.Rationale for the Low Level Primitives Supported in <emphasis role="bold">Boost.Threads</emphasis>The Boost.Threads library supplies a set of low level primitives for
writing multithreaded programs, such as mutexes and condition variables. In
fact, the first release of Boost.Threads supports only these low level
primitives. However, computer science research has shown that use of these
primitives is difficult since it's difficult to mathematically prove that a
usage pattern is correct, meaning it doesn't result in race conditions or
deadlocks. There are several algebras (such as CSP, CCS and Join calculus)
that have been developed to help write provably correct parallel
processes. In order to prove the correctness these processes must be coded
using higher level abstractions. So why does Boost.Threads support the
lower level concepts?The reason is simple: the higher level concepts need to be implemented
using at least some of the lower level concepts. So having portable lower
level concepts makes it easier to develop the higher level concepts and will
allow researchers to experiment with various techniques.Beyond this theoretical application of higher level concepts, however,
the fact remains that many multithreaded programs are written using only the
lower level concepts, so they are useful in and of themselves, even if it's
hard to prove that their usage is correct. Since many users will be familiar
with these lower level concepts but unfamiliar with any of the higher
level concepts, supporting the lower level concepts provides
greater accessibility.Rationale for the Lock DesignProgrammers who are used to multithreaded programming issues will
quickly note that the Boost.Threads design for mutex lock concepts is not
thread-safe (this is
clearly documented as well). At first this may seem like a serious design
flaw. Why have a multithreading primitive that's not thread-safe
itself?A lock object is not a synchronization primitive. A lock object's sole
responsibility is to ensure that a mutex is both locked and unlocked in a
manner that won't result in the common error of locking a mutex and then
forgetting to unlock it. This means that instances of a lock object are only
going to be created, at least in theory, within block scope and won't be
shared between threads. Only the mutex objects will be created outside of
block scope and/or shared between threads. Though it's possible to create a
lock object outside of block scope and to share it between threads, to do so
would not be a typical usage (in fact, to do so would likely be an
error). Nor are there any cases when such usage would be required.Lock objects must maintain some state information. In order to allow a
program to determine if a try_lock or timed_lock was successful the lock
object must retain state indicating the success or failure of the call made
in its constructor. If a lock object were to have such state and remain
thread-safe it would need to synchronize access to the state information
which would result in roughly doubling the time of most operations. Worse,
since checking the state can occur only by a call after construction, we'd
have a race condition if the lock object were shared between threads.So, to avoid the overhead of synchronizing access to the state
information and to avoid the race condition, the Boost.Threads library
simply does nothing to make lock objects thread-safe. Instead, sharing a
lock object between threads results in undefined behavior. Since the only
proper usage of lock objects is within block scope this isn't a problem, and
so long as the lock object is properly used there's no danger of any
multithreading issues.Rationale for NonCopyable Thread TypeProgrammers who are used to C libraries for multithreaded programming
are likely to wonder why Boost.Threads uses a noncopyable design for
boost::thread. After all, the C thread types are
copyable, and you often have a need for copying them within user
code. However, careful comparison of C designs to C++ designs shows a flaw
in this logic.All C types are copyable. It is, in fact, not possible to make a
noncopyable type in C. For this reason types that represent system resources
in C are often designed to behave very similarly to a pointer to dynamic
memory. There's an API for acquiring the resource and an API for releasing
the resource. For memory we have pointers as the type and alloc/free for
the acquisition and release APIs. For files we have FILE* as the type and
fopen/fclose for the acquisition and release APIs. You can freely copy
instances of the types but must manually manage the lifetime of the actual
resource through the acquisition and release APIs.C++ designs recognize that the acquisition and release APIs are error
prone and try to eliminate possible errors by acquiring the resource in the
constructor and releasing it in the destructor. The best example of such a
design is the std::iostream set of classes which can represent the same
resource as the FILE* type in C. A file is opened in the std::fstream's
constructor and closed in its destructor. However, if an iostream were
copyable it could lead to a file being closed twice, an obvious error, so
the std::iostream types are noncopyable by design. This is the same design
used by boost::thread, which is a simple and easy to understand design
that's consistent with other C++ standard types.During the design of boost::thread it was pointed out that it would be
possible to allow it to be a copyable type if some form of "reference
management" were used, such as ref-counting or ref-lists, and many argued
for a boost::thread_ref design instead. The reasoning was that copying
"thread" objects was a typical need in the C libraries, and so presumably
would be in the C++ libraries as well. It was also thought that
implementations could provide more efficient reference management than
wrappers (such as boost::shared_ptr) around a noncopyable thread
concept. Analysis of whether or not these arguments would hold true doesn't
appear to bear them out. To illustrate the analysis we'll first provide
pseudo-code illustrating the six typical usage patterns of a thread
object.1. Use case: Simple creation of a thread.
void foo()
{
create_thread(&bar);
}
2. Use case: Creation of a thread that's later joined.
void foo()
{
thread = create_thread(&bar);
join(thread);
}
3. Use case: Simple creation of several threads in a loop.
void foo()
{
for (int i=0; i<NUM_THREADS; ++i)
create_thread(&bar);
}
4. Use case: Creation of several threads in a loop which are later joined.
void foo()
{
for (int i=0; i<NUM_THREADS; ++i)
threads[i] = create_thread(&bar);
for (int i=0; i<NUM_THREADS; ++i)
threads[i].join();
}
5. Use case: Creation of a thread whose ownership is passed to another object/method.
void foo()
{
thread = create_thread(&bar);
manager.owns(thread);
}
6. Use case: Creation of a thread whose ownership is shared between multiple
objects.
void foo()
{
thread = create_thread(&bar);
manager1.add(thread);
manager2.add(thread);
}
Of these usage patterns there's only one that requires reference
management (number 6). Hopefully it's fairly obvious that this usage pattern
simply won't occur as often as the other usage patterns. So there really
isn't a "typical need" for a thread concept, though there is some
need.Since the need isn't typical we must use different criteria for
deciding on either a thread_ref or thread design. Possible criteria include
ease of use and performance. So let's analyze both of these
carefully.With ease of use we can look at existing experience. The standard C++
objects that represent a system resource, such as std::iostream, are
noncopyable, so we know that C++ programmers must at least be experienced
with this design. Most C++ developers are also used to smart pointers such
as boost::shared_ptr, so we know they can at least adapt to a thread_ref
concept with little effort. So existing experience isn't going to lead us to
a choice.The other thing we can look at is how difficult it is to use both
types for the six usage patterns above. If we find it overly difficult to
use a concept for any of the usage patterns there would be a good argument
for choosing the other design. So we'll code all six usage patterns using
both designs.1. Comparison: simple creation of a thread.
void foo()
{
thread thrd(&bar);
}
void foo()
{
thread_ref thrd = create_thread(&bar);
}
2. Comparison: creation of a thread that's later joined.
void foo()
{
thread thrd(&bar);
thrd.join();
}
void foo()
{
thread_ref thrd =
create_thread(&bar);thrd->join();
}
3. Comparison: simple creation of several threads in a loop.
void foo()
{
for (int i=0; i<NUM_THREADS; ++i)
thread thrd(&bar);
}
void foo()
{
for (int i=0; i<NUM_THREADS; ++i)
thread_ref thrd = create_thread(&bar);
}
4. Comparison: creation of several threads in a loop which are later joined.
void foo()
{
std::auto_ptr<thread> threads[NUM_THREADS];
for (int i=0; i<NUM_THREADS; ++i)
threads[i] = std::auto_ptr<thread>(new thread(&bar));
for (int i= 0; i<NUM_THREADS;
++i)threads[i]->join();
}
void foo()
{
thread_ref threads[NUM_THREADS];
for (int i=0; i<NUM_THREADS; ++i)
threads[i] = create_thread(&bar);
for (int i= 0; i<NUM_THREADS;
++i)threads[i]->join();
}
5. Comparison: creation of a thread whose ownership is passed to another object/method.
void foo()
{
thread thrd* = new thread(&bar);
manager.owns(thread);
}
void foo()
{
thread_ref thrd = create_thread(&bar);
manager.owns(thrd);
}
6. Comparison: creation of a thread whose ownership is shared
between multiple objects.
void foo()
{
boost::shared_ptr<thread> thrd(new thread(&bar));
manager1.add(thrd);
manager2.add(thrd);
}
void foo()
{
thread_ref thrd = create_thread(&bar);
manager1.add(thrd);
manager2.add(thrd);
}
This shows the usage patterns being nearly identical in complexity for
both designs. The only actual added complexity occurs because of the use of
operator new in
(4),
(5), and
(6);
and the use of std::auto_ptr and boost::shared_ptr in
(4) and
(6)
respectively. However, that's not really
much added complexity, and C++ programmers are used to using these idioms
anyway. Some may dislike the presence of operator new in user code, but
this can be eliminated by proper design of higher level concepts, such as
the boost::thread_group class that simplifies example
(4)
down to:
void foo()
{
thread_group threads;
for (int i=0; i<NUM_THREADS; ++i)
threads.create_thread(&bar);
threads.join_all();
}
So ease of use is really a wash and not much help in picking a
design.So what about performance? Looking at the above code examples,
we can analyze the theoretical impact to performance that both designs
have. For (1)
we can see that platforms that don't have a ref-counted native
thread type (POSIX, for instance) will be impacted by a thread_ref
design. Even if the native thread type is ref-counted there may be an impact
if more state information has to be maintained for concepts foreign to the
native API, such as clean up stacks for Win32 implementations.
For (2)
and (3)
the performance impact will be identical to
(1).
For (4)
things get a little more interesting and we find that theoretically at least
the thread_ref may perform faster since the thread design requires dynamic
memory allocation/deallocation. However, in practice there may be dynamic
allocation for the thread_ref design as well, it will just be hidden from
the user. As long as the implementation has to do dynamic allocations the
thread_ref loses again because of the reference management. For
(5) we see
the same impact as we do for
(4).
For (6)
we still have a possible impact to
the thread design because of dynamic allocation but thread_ref no longer
suffers because of its reference management, and in fact, theoretically at
least, the thread_ref may do a better job of managing the references. All of
this indicates that thread wins for
(1),
(2) and
(3); with
(4)
and (5) the
winner depending on the implementation and the platform but with the thread design
probably having a better chance; and with
(6)
it will again depend on the
implementation and platform but this time we favor thread_ref
slightly. Given all of this it's a narrow margin, but the thread design
prevails.Given this analysis, and the fact that noncopyable objects for system
resources are the normal designs that C++ programmers are used to dealing
with, the Boost.Threads library has gone with a noncopyable design.Rationale for not providing <emphasis>Event Variables</emphasis>Event variables are simply far too
error-prone. boost::condition variables are a much safer
alternative. [Note that Graphical User Interface events are
a different concept, and are not what is being discussed here.]Event variables were one of the first synchronization primitives. They
are still used today, for example, in the native Windows multithreading
API. Yet both respected computer science researchers and experienced
multithreading practitioners believe event variables are so inherently
error-prone that they should never be used, and thus should not be part of a
multithreading library.Per Brinch Hansen analyzed event variables in some
detail, pointing out [emphasis his] that "event operations force
the programmer to be aware of the relative speeds of the sending and
receiving processes". His summary:
We must therefore conclude that event variables of the previous type
are impractical for system design. The effect of an interaction
between two processes must be independent of the speed at which it is
carried out.
Experienced programmers using the Windows platform today report that
event variables are a continuing source of errors, even after previous bad
experiences caused them to be very careful in their use of event
variables. Overt problems can be avoided, for example, by teaming the event
variable with a mutex, but that may just convert a race condition into another
problem, such as excessive resource use. One of the most distressing aspects
of the experience reports is the claim that many defects are latent. That
is, the programs appear to work correctly, but contain hidden timing
dependencies which will cause them to fail when environmental factors or
usage patterns change, altering relative thread timings.The decision to exclude event variables from Boost.Threads has been
surprising to some Windows programmers. They have written programs which
work using event variables, and wonder what the problem is. It seems similar
to the "goto considered harmful" controversy of 30 years ago. It isn't that
events, like gotos, can't be made to work, but rather that virtually all
programs using alternatives will be easier to write, debug, read, maintain,
and will be less likely to contain latent defects.[Rationale provided by Beman Dawes]ReferenceHeader <<ulink url="../../boost/thread/barrier.hpp">boost/thread/barrier.hpp</ulink>>namespace boost {
class barrier;
}Class barrier3boost::barrierAn object of class barrier is a synchronization
primitive used to cause a set of threads to wait until they each perform a
certain function or each reach a particular point in their execution.class barrier : private boost::noncopyable // Exposition only
{
public:
// construct/copy/destruct
barrier(size_t);
~barrier();
// waitingbool wait();
};DescriptionWhen a barrier is created, it is initialized with a thread count N.
The first N-1 calls to wait() will all cause their threads to be blocked.
The Nth call to wait() will allow all of the waiting threads, including
the Nth thread, to be placed in a ready state. The Nth call will also "reset"
the barrier such that, if an additional N+1th call is made to wait(),
it will be as though this were the first call to wait(); in other
words, the N+1th to 2N-1th calls to wait() will cause their
threads to be blocked, and the 2Nth call to wait() will allow all of
the waiting threads, including the 2Nth thread, to be placed in a ready state
and reset the barrier. This functionality allows the same set of N threads to re-use
a barrier object to synchronize their execution at multiple points during their
execution.See for definitions of thread
states blocked
and ready.
Note that "waiting" is a synonym for blocked.<anchor id="barrierconstruct-copy-destruct"/><computeroutput>barrier</computeroutput> construct/copy/destructbarrier(size_t count);EffectsConstructs a barrier object that
will cause count threads to block on a call to wait().
~barrier();EffectsDestroys *this. If threads are still executing
their wait() operations, the behavior for these threads is undefined.
<anchor id="id480142-bb"/><computeroutput>barrier</computeroutput> waitingboolwait();EffectsWait until N threads call wait(), where
N equals the count provided to the constructor for the
barrier object.Note that if the barrier is
destroyed before wait() can return, the behavior is
undefined.ReturnsExactly one of the N threads will receive a return value
of true, the others will receive a value of false.
Precisely which thread receives the return value of true will
be implementation-defined. Applications can use this value to designate one
thread as a leader that will take a certain action, and the other threads
emerging from the barrier can wait for that action to take place.Header <<ulink url="../../boost/thread/condition.hpp">boost/thread/condition.hpp</ulink>>namespace boost {
class condition;
}Class condition3boost::conditionAn object of class condition is a
synchronization primitive used to cause a thread to wait until a
particular shared-data condition (or time) is met.class condition : private boost::noncopyable // Exposition only
{
public:
// construct/copy/destruct
condition();
~condition();
// notificationvoid notify_one();
void notify_all();
// waitingtemplate<typename ScopedLock> void wait(ScopedLock&);
template<typename ScopedLock, typename Pred> void wait(ScopedLock&, Pred);
template<typename ScopedLock>
bool timed_wait(ScopedLock&, const boost::xtime&);
template<typename ScopedLock, typename Pred>
bool timed_wait(ScopedLock&, Pred);
};DescriptionA condition object is always used in
conjunction with a mutex
object (an object whose type is a model of a Mutex or one of its
refinements). The mutex object must be locked prior to waiting on the
condition, which is verified by passing a lock object (an object whose
type is a model of Lock or
one of its refinements) to the condition object's
wait functions. Upon blocking on the condition
object, the thread unlocks the mutex object. When the thread returns
from a call to one of the condition object's wait
functions the mutex object is again locked. The tricky unlock/lock
sequence is performed automatically by the
condition object's wait functions.The condition type is often used to
implement the Monitor Object and other important patterns (see
and ). Monitors are one
of the most important patterns for creating reliable multithreaded
programs.See for definitions of thread states
blocked and ready. Note that "waiting" is a synonym for blocked.<anchor id="conditionconstruct-copy-destruct"/><computeroutput>condition</computeroutput> construct/copy/destructcondition();EffectsConstructs a condition
object.~condition();EffectsDestroys *this.<anchor id="id457659-bb"/><computeroutput>condition</computeroutput> notificationvoidnotify_one();EffectsIf there is a thread waiting on *this,
change that thread's state to ready. Otherwise there is no
effect.NotesIf more than one thread is waiting on *this,
it is unspecified which is made ready. After returning to a ready
state the notified thread must still acquire the mutex again (which
occurs within the call to one of the condition
object's wait functions.)voidnotify_all();EffectsChange the state of all threads waiting on
*this to ready. If there are no waiting threads,
notify_all() has no effect.<anchor id="id439939-bb"/><computeroutput>condition</computeroutput> waitingtemplate<typename ScopedLock> voidwait(ScopedLock& lock);RequiresScopedLock meets the ScopedLock
requirements.EffectsReleases the lock on the mutex object
associated with lock, blocks the current thread of execution
until readied by a call to this->notify_one()
or this->notify_all(), and then reacquires the
lock.Throwslock_error if
!lock.locked()template<typename ScopedLock, typename Pred>
voidwait(ScopedLock& lock, Pred pred);RequiresScopedLock meets the ScopedLock
requirements and the return from pred() is
convertible to bool.EffectsAs if: while (!pred())
wait(lock)Throwslock_error if
!lock.locked()template<typename ScopedLock>
booltimed_wait(ScopedLock& lock, const boost::xtime& xt);RequiresScopedLock meets the ScopedLock
requirements.EffectsReleases the lock on the mutex object
associated with lock, blocks the current thread of execution
until readied by a call to this->notify_one()
or this->notify_all(), or until time xt
is reached, and then reacquires the lock.Returnsfalse if time xt is reached,
otherwise true.Throwslock_error if
!lock.locked()template<typename ScopedLock, typename Pred>
booltimed_wait(ScopedLock& lock, Pred pred);RequiresScopedLock meets the ScopedLock
requirements and the return from pred() is
convertible to bool.EffectsAs if: while (!pred()) { if (!timed_wait(lock,
xt)) return false; } return true;Returnsfalse if xt is reached,
otherwise true.Throwslock_error if
!lock.locked()Header <<ulink url="../../boost/thread/exceptions.hpp">boost/thread/exceptions.hpp</ulink>>namespace boost {
class lock_error;
class thread_resource_error;
}Class lock_error3boost::lock_errorThe lock_error class defines an exception type thrown
to indicate a locking related error has been detected.class lock_error : publicstd::logical_error {
public:
// construct/copy/destruct
lock_error();
};DescriptionExamples of errors indicated by a lock_error exception
include a lock operation which can be determined to result in a
deadlock, or unlock operations attempted by a thread that does
not own the lock.<anchor id="lock_errorconstruct-copy-destruct"/><computeroutput>lock_error</computeroutput> construct/copy/destructlock_error();EffectsConstructs a lock_error object.
Class thread_resource_error3boost::thread_resource_errorThe thread_resource_error class
defines an exception type that is thrown by constructors in the
Boost.Threads library when thread-related resources can not be
acquired.class thread_resource_error : publicstd::runtime_error {
public:
// construct/copy/destruct
thread_resource_error();
};Descriptionthread_resource_error is used
only when thread-related resources cannot be acquired; memory
allocation failures are indicated by
std::bad_alloc.<anchor id="thread_resource_errorconstruct-copy-destruct"/><computeroutput>thread_resource_error</computeroutput> construct/copy/destructthread_resource_error();EffectsConstructs a thread_resource_error
object.Header <<ulink url="../../boost/thread/mutex.hpp">boost/thread/mutex.hpp</ulink>>namespace boost {
class mutex;
class try_mutex;
class timed_mutex;
}Class mutex3boost::mutexThe mutex class is a model of the
Mutex concept.class mutex : private boost::noncopyable // Exposition only
{
public:
// typestypedefimplementation-defined scoped_lock;
// construct/copy/destruct
mutex();
~mutex();
};DescriptionThe mutex class is a model of the
Mutex concept.
It should be used to synchronize access to shared resources using
Unspecified
locking mechanics.For classes that model related mutex concepts, see
try_mutex and timed_mutex.For Recursive
locking mechanics, see recursive_mutex,
recursive_try_mutex, and recursive_timed_mutex.
The mutex class supplies the following typedef,
which models
the specified locking strategy:
Lock NameLock Conceptscoped_lockScopedLockThe mutex class uses an
Unspecified
locking strategy, so attempts to recursively lock a mutex
object or attempts to unlock one by threads that don't own a lock on it result in
undefined behavior.
This strategy allows implementations to be as efficient as possible
on any given platform. It is, however, recommended that
implementations include debugging support to detect misuse when
NDEBUG is not defined.Like all
mutex models
in Boost.Threads, mutex leaves the
scheduling policy
as Unspecified.
Programmers should make no assumptions about the order in which
waiting threads acquire a lock.<anchor id="mutexconstruct-copy-destruct"/><computeroutput>mutex</computeroutput> construct/copy/destructmutex();EffectsConstructs a mutex object.
Postconditions*this is in an unlocked state.
~mutex();EffectsDestroys a mutex object.Requires*this is in an unlocked state.NotesDanger: Destruction of a
locked mutex is a serious programming error resulting in undefined
behavior such as a program crash.Class try_mutex3boost::try_mutexThe try_mutex class is a model of the
TryMutex concept.class try_mutex : private boost::noncopyable // Exposition only
{
public:
// typestypedefimplementation-defined scoped_lock;
typedefimplementation-defined scoped_try_lock;
// construct/copy/destruct
try_mutex();
~try_mutex();
};DescriptionThe try_mutex class is a model of the
TryMutex concept.
It should be used to synchronize access to shared resources using
Unspecified
locking mechanics.For classes that model related mutex concepts, see
mutex and timed_mutex.For Recursive
locking mechanics, see recursive_mutex,
recursive_try_mutex, and recursive_timed_mutex.
The try_mutex class supplies the following typedefs,
which model
the specified locking strategies:
Lock NameLock Conceptscoped_lockScopedLockscoped_try_lockScopedTryLockThe try_mutex class uses an
Unspecified
locking strategy, so attempts to recursively lock a try_mutex
object or attempts to unlock one by threads that don't own a lock on it result in
undefined behavior.
This strategy allows implementations to be as efficient as possible
on any given platform. It is, however, recommended that
implementations include debugging support to detect misuse when
NDEBUG is not defined.Like all
mutex models
in Boost.Threads, try_mutex leaves the
scheduling policy
as Unspecified.
Programmers should make no assumptions about the order in which
waiting threads acquire a lock.<anchor id="try_mutexconstruct-copy-destruct"/><computeroutput>try_mutex</computeroutput> construct/copy/destructtry_mutex();EffectsConstructs a try_mutex object.
Postconditions*this is in an unlocked state.
~try_mutex();EffectsDestroys a try_mutex object.
Requires*this is in an unlocked state.NotesDanger: Destruction of a
locked mutex is a serious programming error resulting in undefined
behavior such as a program crash.Class timed_mutex3boost::timed_mutexThe timed_mutex class is a model of the
TimedMutex concept.class timed_mutex : private boost::noncopyable // Exposition only
{
public:
// typestypedefimplementation-defined scoped_lock;
typedefimplementation-defined scoped_try_lock;
typedefimplementation-defined scoped_timed_lock;
// construct/copy/destruct
timed_mutex();
~timed_mutex();
};DescriptionThe timed_mutex class is a model of the
TimedMutex concept.
It should be used to synchronize access to shared resources using
Unspecified
locking mechanics.For classes that model related mutex concepts, see
mutex and try_mutex.For Recursive
locking mechanics, see recursive_mutex,
recursive_try_mutex, and recursive_timed_mutex.
The timed_mutex class supplies the following typedefs,
which model
the specified locking strategies:
Lock NameLock Conceptscoped_lockScopedLockscoped_try_lockScopedTryLockscoped_timed_lockScopedTimedLockThe timed_mutex class uses an
Unspecified
locking strategy, so attempts to recursively lock a timed_mutex
object or attempts to unlock one by threads that don't own a lock on it result in
undefined behavior.
This strategy allows implementations to be as efficient as possible
on any given platform. It is, however, recommended that
implementations include debugging support to detect misuse when
NDEBUG is not defined.Like all
mutex models
in Boost.Threads, timed_mutex leaves the
scheduling policy
as Unspecified.
Programmers should make no assumptions about the order in which
waiting threads acquire a lock.<anchor id="timed_mutexconstruct-copy-destruct"/><computeroutput>timed_mutex</computeroutput> construct/copy/destructtimed_mutex();EffectsConstructs a timed_mutex object.
Postconditions*this is in an unlocked state.
~timed_mutex();EffectsDestroys a timed_mutex object.Requires*this is in an unlocked state.NotesDanger: Destruction of a
locked mutex is a serious programming error resulting in undefined
behavior such as a program crash.Header <<ulink url="../../boost/thread/once.hpp">boost/thread/once.hpp</ulink>>
BOOST_ONCE_INITnamespace boost {
typedefimplementation-defined once_flag; // The call_once function and
once_flag type (statically initialized to
BOOST_ONCE_INIT) can be used to run a
routine exactly once. This can be used to initialize data in a
thread-safe
manner.
call_once(void (*func)(), once_flag&);
}Macro BOOST_ONCE_INIT3BOOST_ONCE_INITThe call_once function and
once_flag type (statically initialized to
BOOST_ONCE_INIT) can be used to run a
routine exactly once. This can be used to initialize data in a
thread-safe
manner.BOOST_ONCE_INITDescriptionThe implementation-defined macro
BOOST_ONCE_INIT is a constant value used to
initialize once_flag instances to indicate that the
logically associated routine has not been run yet. See
call_once for more details.Function call_once3boost::call_onceThe call_once function and
once_flag type (statically initialized to
BOOST_ONCE_INIT) can be used to run a
routine exactly once. This can be used to initialize data in a
thread-safe
manner.
call_once(void (*func)() func, once_flag& flag);DescriptionExample usage is as follows://Example usage:
boost::once_flag once = BOOST_ONCE_INIT;
void init()
{
//...
}
void thread_proc()
{
boost::call_once(&init, once);
}RequiresThe function func shall not throw
exceptions.EffectsAs if (in an atomic fashion):
if (flag == BOOST_ONCE_INIT) func();Postconditionsflag != BOOST_ONCE_INITHeader <<ulink url="../../boost/thread/recursive_mutex.hpp">boost/thread/recursive_mutex.hpp</ulink>>namespace boost {
class recursive_mutex;
class recursive_try_mutex;
class recursive_timed_mutex;
}Class recursive_mutex3boost::recursive_mutexThe recursive_mutex class is a model of the
Mutex concept.class recursive_mutex : private boost::noncopyable // Exposition only
{
public:
// typestypedefimplementation-defined scoped_lock;
// construct/copy/destruct
recursive_mutex();
~recursive_mutex();
};DescriptionThe recursive_mutex class is a model of the
Mutex concept.
It should be used to synchronize access to shared resources using
Recursive
locking mechanics.For classes that model related mutex concepts, see
recursive_try_mutex and recursive_timed_mutex.For Unspecified
locking mechanics, see mutex,
try_mutex, and timed_mutex.
The recursive_mutex class supplies the following typedef,
which models the specified locking strategy:
The recursive_mutex class uses a
Recursive
locking strategy, so attempts to recursively lock a
recursive_mutex object
succeed and an internal "lock count" is maintained.
Attempts to unlock a recursive_mutex object
by threads that don't own a lock on it result in
undefined behavior.Like all
mutex models
in Boost.Threads, recursive_mutex leaves the
scheduling policy
as Unspecified.
Programmers should make no assumptions about the order in which
waiting threads acquire a lock.<anchor id="recursive_mutexconstruct-copy-destruct"/><computeroutput>recursive_mutex</computeroutput> construct/copy/destructrecursive_mutex();EffectsConstructs a recursive_mutex object.
Postconditions*this is in an unlocked state.
~recursive_mutex();EffectsDestroys a recursive_mutex object.Requires*this is in an unlocked state.NotesDanger: Destruction of a
locked mutex is a serious programming error resulting in undefined
behavior such as a program crash.Class recursive_try_mutex3boost::recursive_try_mutexThe recursive_try_mutex class is a model of the
TryMutex concept.class recursive_try_mutex : private boost::noncopyable // Exposition only
{
public:
// typestypedefimplementation-defined scoped_lock;
typedefimplementation-defined scoped_try_lock;
// construct/copy/destruct
recursive_try_mutex();
~recursive_try_mutex();
};DescriptionThe recursive_try_mutex class is a model of the
TryMutex concept.
It should be used to synchronize access to shared resources using
Recursive
locking mechanics.For classes that model related mutex concepts, see
recursive_mutex and recursive_timed_mutex.For Unspecified
locking mechanics, see mutex,
try_mutex, and timed_mutex.
The recursive_try_mutex class supplies the following typedefs,
which model the specified locking strategies:
The recursive_try_mutex class uses a
Recursive
locking strategy, so attempts to recursively lock a
recursive_try_mutex object
succeed and an internal "lock count" is maintained.
Attempts to unlock a recursive_mutex object
by threads that don't own a lock on it result in
undefined behavior.Like all
mutex models
in Boost.Threads, recursive_try_mutex leaves the
scheduling policy
as Unspecified.
Programmers should make no assumptions about the order in which
waiting threads acquire a lock.<anchor id="recursive_try_mutexconstruct-copy-destruct"/><computeroutput>recursive_try_mutex</computeroutput> construct/copy/destructrecursive_try_mutex();EffectsConstructs a recursive_try_mutex object.
Postconditions*this is in an unlocked state.
~recursive_try_mutex();EffectsDestroys a recursive_try_mutex object.
Requires*this is in an unlocked state.NotesDanger: Destruction of a
locked mutex is a serious programming error resulting in undefined
behavior such as a program crash.Class recursive_timed_mutex3boost::recursive_timed_mutexThe recursive_timed_mutex class is a model of the
TimedMutex concept.class recursive_timed_mutex : private boost::noncopyable // Exposition only
{
public:
// typestypedefimplementation-defined scoped_lock;
typedefimplementation-defined scoped_try_lock;
typedefimplementation-defined scoped_timed_lock;
// construct/copy/destruct
recursive_timed_mutex();
~recursive_timed_mutex();
};DescriptionThe recursive_timed_mutex class is a model of the
TimedMutex concept.
It should be used to synchronize access to shared resources using
Recursive
locking mechanics.For classes that model related mutex concepts, see
recursive_mutex and recursive_try_mutex.For Unspecified
locking mechanics, see mutex,
try_mutex, and timed_mutex.
The recursive_timed_mutex class supplies the following typedefs,
which model the specified locking strategies:
The recursive_timed_mutex class uses a
Recursive
locking strategy, so attempts to recursively lock a
recursive_timed_mutex object
succeed and an internal "lock count" is maintained.
Attempts to unlock a recursive_mutex object
by threads that don't own a lock on it result in
undefined behavior.Like all
mutex models
in Boost.Threads, recursive_timed_mutex leaves the
scheduling policy
as Unspecified.
Programmers should make no assumptions about the order in which
waiting threads acquire a lock.<anchor id="recursive_timed_mutexconstruct-copy-destruct"/><computeroutput>recursive_timed_mutex</computeroutput> construct/copy/destructrecursive_timed_mutex();EffectsConstructs a recursive_timed_mutex object.
Postconditions*this is in an unlocked state.
~recursive_timed_mutex();EffectsDestroys a recursive_timed_mutex object.Requires*this is in an unlocked state.NotesDanger: Destruction of a
locked mutex is a serious programming error resulting in undefined
behavior such as a program crash.Header <<ulink url="../../boost/thread/read_write_mutex.hpp">boost/thread/read_write_mutex.hpp</ulink>>namespace boost {
class read_write_mutex;
class try_read_write_mutex;
class