Skip to content

Commit

Permalink
add Doxygen docs to the basic_any and add tests on const unique_any (…
Browse files Browse the repository at this point in the history 
…refs #24)
  • Loading branch information
@apolukhin
apolukhin committed May 9, 2023
1 parent bf3c89b commit fd44ca3
Show file tree
Hide file tree
Showing 3 changed files with 162 additions and 28 deletions.
12 changes: 6 additions & 6 deletions include/boost/any.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -339,7 +339,7 @@ namespace boost
}

/// \returns Pointer to a ValueType stored in `operand`, nullptr if
/// `operand` does not contain specified ValueType.
/// `operand` does not contain specified `ValueType`.
template<typename ValueType>
ValueType * any_cast(any * operand) BOOST_NOEXCEPT
{
Expand All @@ -349,7 +349,7 @@ namespace boost
}

/// \returns Const pointer to a ValueType stored in `operand`, nullptr if
/// `operand` does not contain specified ValueType.
/// `operand` does not contain specified `ValueType`.
template<typename ValueType>
inline const ValueType * any_cast(const any * operand) BOOST_NOEXCEPT
{
Expand Down Expand Up @@ -388,9 +388,9 @@ namespace boost
#endif
}

/// \returns ValueType stored in `operand`
/// \returns `ValueType` stored in `operand`
/// \throws boost::bad_any_cast if `operand` does not contain
/// specified ValueType.
/// specified `ValueType`.
template<typename ValueType>
inline ValueType any_cast(const any & operand)
{
Expand All @@ -399,9 +399,9 @@ namespace boost
}

#ifndef BOOST_NO_CXX11_RVALUE_REFERENCES
/// \returns ValueType stored in `operand`, leving the `operand` empty.
/// \returns `ValueType` stored in `operand`, leaving the `operand` empty.
/// \throws boost::bad_any_cast if `operand` does not contain
/// specified ValueType.
/// specified `ValueType`.
template<typename ValueType>
inline ValueType any_cast(any&& operand)
{
Expand Down
168 changes: 146 additions & 22 deletions include/boost/any/basic_any.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@
# pragma once
#endif

/// \file boost/any/basic_any.hpp
/// \brief \copybrief boost::anys::basic_any

#include <boost/any/bad_any_cast.hpp>
#include <boost/any/fwd.hpp>
#include <boost/assert.hpp>
Expand All @@ -38,6 +41,25 @@ namespace boost {

namespace anys {

/// \brief A class with customizable Small Object Optimization whose
/// instances can hold instances of any type that satisfies
/// \forcedlink{ValueType} requirements. Use boost::any instead if not sure.
///
/// boost::anys::basic_any is the drop-in replacement for boost::any
/// that provides controll over Small Object Optimization via
/// `OptimizeForSize` and `OptimizeForAlignment` template parameters.
///
/// There are certain applications that require boost::any
/// functionality, do know the typical/maximal size of the stored object and
/// wish to avoid dynamic memory allocation overhead. For the convenience
/// such applications may create a typedef for boost::anys::basic_any
/// with the `OptimizeForSize` and `OptimizeForAlignment` template
/// parameters set to typical/maximal size and alignment of types
/// respectively. Memory allocation would be avoided for storing nothrow
/// move constructible types with size and alignment less than or
/// equal to the `OptimizeForSize` and `OptimizeForAlignment` values.
///
/// Otherwise just use boost::any.
template <std::size_t OptimizeForSize, std::size_t OptimizeForAlignment>
class basic_any
{
Expand Down Expand Up @@ -195,11 +217,22 @@ namespace anys {

public: // structors

/// \post this->empty() is true.
BOOST_CONSTEXPR basic_any() BOOST_NOEXCEPT
: man(0), content()
{
}

/// Makes a copy of `value`, so
/// that the initial content of the new instance is equivalent
/// in both type and value to `value`.
///
/// Does not dynamically allocate if `ValueType` is nothrow
/// move constructible and `sizeof(value) <= OptimizeForSize` and
/// `alignof(value) <= OptimizeForAlignment`.
///
/// \throws std::bad_alloc or any exceptions arising from the copy
/// constructor of the contained type.
template<typename ValueType>
basic_any(const ValueType & value)
: man(0), content()
Expand All @@ -215,6 +248,14 @@ namespace anys {
create(*this, value, is_small_object<ValueType>());
}

/// 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.
///
/// \throws May fail with a `std::bad_alloc`
/// exception or any exceptions arising from the copy
/// constructor of the contained type.
basic_any(const basic_any & other)
: man(0), content()
{
Expand All @@ -225,7 +266,12 @@ namespace anys {
}

#ifndef BOOST_NO_CXX11_RVALUE_REFERENCES
// Move constructor
/// Move constructor that moves content of
/// `other` into new instance and leaves `other` empty.
///
/// \pre C++11 compatible compiler
/// \post other->empty() is true
/// \throws Nothing.
basic_any(basic_any&& other) BOOST_NOEXCEPT
: man(0), content()
{
Expand All @@ -235,7 +281,17 @@ namespace anys {
}
}

// Perfect forwarding of ValueType
/// Forwards `value`, so
/// that the initial content of the new instance is equivalent
/// in both type and value to `value` before the forward.
///
/// Does not dynamically allocate if `ValueType` is nothrow
/// move constructible and `sizeof(value) <= OptimizeForSize` and
/// `alignof(value) <= OptimizeForAlignment`.
///
/// \pre C++11 compatible compiler.
/// \throws std::bad_alloc or any exceptions arising from the move or
/// copy constructor of the contained type.
template<typename ValueType>
basic_any(ValueType&& value
, typename boost::disable_if<boost::is_same<basic_any&, ValueType> >::type* = 0 // disable if value has type `basic_any&`
Expand All @@ -255,6 +311,9 @@ namespace anys {
}
#endif

/// Releases any and all resources used in management of instance.
///
/// \throws Nothing.
~basic_any() BOOST_NOEXCEPT
{
if (man)
Expand All @@ -265,6 +324,10 @@ namespace anys {

public: // modifiers

/// Exchange of the contents of `*this` and `rhs`.
///
/// \returns `*this`
/// \throws Nothing.
basic_any & swap(basic_any & rhs) BOOST_NOEXCEPT
{
if (this == &rhs)
Expand All @@ -290,8 +353,36 @@ namespace anys {
return *this;
}

/// Copies 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()`.
///
/// \throws std::bad_alloc
/// or any exceptions arising from the copy constructor of the
/// contained type. Assignment satisfies the strong guarantee
/// of exception safety.
basic_any & operator=(const basic_any& rhs)
{
basic_any(rhs).swap(*this);
return *this;
}


#ifdef BOOST_NO_CXX11_RVALUE_REFERENCES
/// Makes a copy of `rhs`,
/// discarding previous content, so that the new content of is
/// equivalent in both type and value to
/// `rhs`.
///
/// Does not dynamically allocate if `ValueType` is nothrow
/// move constructible and `sizeof(value) <= OptimizeForSize` and
/// `alignof(value) <= OptimizeForAlignment`.
///
/// \throws std::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>
basic_any & operator=(const ValueType & rhs)
{
Expand All @@ -307,28 +398,37 @@ namespace anys {
return *this;
}

basic_any & operator=(basic_any rhs)
{
rhs.swap(*this);
return *this;
}

#else
basic_any & operator=(const basic_any& rhs)
{
basic_any(rhs).swap(*this);
return *this;
}

// move assignment
/// Moves 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` before move, or empty if
/// `rhs.empty()`.
///
/// \pre C++11 compatible compiler.
/// \post `rhs->empty()` is true
/// \throws Nothing.
basic_any & operator=(basic_any&& rhs) BOOST_NOEXCEPT
{
rhs.swap(*this);
basic_any().swap(rhs);
return *this;
}

// Perfect forwarding of ValueType
/// Forwards `rhs`,
/// discarding previous content, so that the new content of is
/// equivalent in both type and value to
/// `rhs` before forward.
///
/// Does not dynamically allocate if `ValueType` is nothrow
/// move constructible and `sizeof(value) <= OptimizeForSize` and
/// `alignof(value) <= OptimizeForAlignment`.
///
/// \pre C++11 compatible compiler.
/// \throws std::bad_alloc
/// or any exceptions arising from the move or copy constructor of the
/// contained type. Assignment satisfies the strong guarantee
/// of exception safety.
template <class ValueType>
basic_any & operator=(ValueType&& rhs)
{
Expand All @@ -348,16 +448,25 @@ namespace anys {

public: // queries

/// \returns `true` if instance is empty, otherwise `false`.
/// \throws Nothing.
bool empty() const BOOST_NOEXCEPT
{
return !man;
}

/// \post this->empty() is true
void clear() BOOST_NOEXCEPT
{
basic_any().swap(*this);
}

/// \returns the `typeid` of the
/// contained value if instance is non-empty, otherwise
/// `typeid(void)`.
///
/// Useful for querying against types known either at compile time or
/// only at runtime.
const boost::typeindex::type_info& type() const BOOST_NOEXCEPT
{
return man
Expand All @@ -383,32 +492,41 @@ namespace anys {
} content;
};

/// Exchange of the contents of `lhs` and `rhs`.
/// \throws Nothing.
template<std::size_t OptimizeForSize, std::size_t OptimizeForAlignment>
void swap(basic_any<OptimizeForSize, OptimizeForAlignment>& lhs, basic_any<OptimizeForSize, OptimizeForAlignment>& rhs) BOOST_NOEXCEPT
{
lhs.swap(rhs);
}

/// \returns Pointer to a ValueType stored in `operand`, nullptr if
/// `operand` does not contain specified `ValueType`.
template<typename ValueType, std::size_t Size, std::size_t Alignment>
ValueType * any_cast(basic_any<Size, Alignment> * operand) BOOST_NOEXCEPT
{
return operand->man ?
static_cast<typename remove_cv<ValueType>::type *>(operand->man(basic_any<Size, Alignment>::AnyCast, *operand, 0, &boost::typeindex::type_id<ValueType>().type_info()))
static_cast<typename boost::remove_cv<ValueType>::type *>(operand->man(basic_any<Size, Alignment>::AnyCast, *operand, 0, &boost::typeindex::type_id<ValueType>().type_info()))
: 0;
}

/// \returns Const pointer to a ValueType stored in `operand`, nullptr if
/// `operand` does not contain specified `ValueType`.
template<typename ValueType, std::size_t OptimizeForSize, std::size_t OptimizeForAlignment>
inline const ValueType * any_cast(const basic_any<OptimizeForSize, OptimizeForAlignment> * operand) BOOST_NOEXCEPT
{
return any_cast<ValueType>(const_cast<basic_any<OptimizeForSize, OptimizeForAlignment> *>(operand));
return boost::anys::any_cast<ValueType>(const_cast<basic_any<OptimizeForSize, OptimizeForAlignment> *>(operand));
}

/// \returns ValueType stored in `operand`
/// \throws boost::bad_any_cast if `operand` does not contain
/// specified ValueType.
template<typename ValueType, std::size_t OptimizeForSize, std::size_t OptimizeForAlignment>
ValueType any_cast(basic_any<OptimizeForSize, OptimizeForAlignment> & operand)
{
typedef typename remove_reference<ValueType>::type nonref;

nonref * result = any_cast<nonref>(boost::addressof(operand));
nonref * result = boost::anys::any_cast<nonref>(boost::addressof(operand));
if(!result)
boost::throw_exception(bad_any_cast());

Expand All @@ -432,14 +550,20 @@ namespace anys {
#endif
}

/// \returns `ValueType` stored in `operand`
/// \throws boost::bad_any_cast if `operand` does not contain
/// specified `ValueType`.
template<typename ValueType, std::size_t OptimizeForSize, std::size_t OptimizeForAlignment>
inline ValueType any_cast(const basic_any<OptimizeForSize, OptimizeForAlignment> & operand)
{
typedef typename remove_reference<ValueType>::type nonref;
return any_cast<const nonref &>(const_cast<basic_any<OptimizeForSize, OptimizeForAlignment> &>(operand));
return boost::anys::any_cast<const nonref &>(const_cast<basic_any<OptimizeForSize, OptimizeForAlignment> &>(operand));
}

#ifndef BOOST_NO_CXX11_RVALUE_REFERENCES
/// \returns `ValueType` stored in `operand`, leaving the `operand` empty.
/// \throws boost::bad_any_cast if `operand` does not contain
/// specified `ValueType`.
template<typename ValueType, std::size_t OptimizeForSize, std::size_t OptimizeForAlignment>
inline ValueType any_cast(basic_any<OptimizeForSize, OptimizeForAlignment>&& operand)
{
Expand All @@ -448,7 +572,7 @@ namespace anys {
|| boost::is_const< typename boost::remove_reference<ValueType>::type >::value,
"boost::any_cast shall not be used for getting nonconst references to temporary objects"
);
return any_cast<ValueType>(operand);
return boost::anys::any_cast<ValueType>(operand);
}
#endif

Expand All @@ -467,7 +591,7 @@ namespace anys {
template<typename ValueType, std::size_t OptimizeForSize, std::size_t OptimizeForAlignment>
inline const ValueType * unsafe_any_cast(const basic_any<OptimizeForSize, OptimizeForAlignment> * operand) BOOST_NOEXCEPT
{
return unsafe_any_cast<ValueType>(const_cast<basic_any<OptimizeForSize, OptimizeForAlignment> *>(operand));
return boost::anys::unsafe_any_cast<ValueType>(const_cast<basic_any<OptimizeForSize, OptimizeForAlignment> *>(operand));
}

} // namespace anys
Expand Down
10 changes: 10 additions & 0 deletions test/unique_any/base.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,15 @@ void test_basic() {
BOOST_TEST(!b.has_value());
}

void test_const() {
const boost::anys::unique_any a = 42;
BOOST_TEST(a.has_value());
BOOST_TEST_EQ(boost::any_cast<int>(a), 42);
BOOST_TEST_EQ(boost::anys::any_cast<int>(a), 42);
BOOST_TEST_EQ(boost::any_cast<const int&>(a), 42);
BOOST_TEST_EQ(boost::anys::any_cast<const int&>(a), 42);
}

void test_bad_any_cast() {
boost::anys::unique_any a;
a.emplace<int>(42);
Expand Down Expand Up @@ -118,6 +127,7 @@ void test_swap() {

int main() {
test_basic();
test_const();
test_bad_any_cast();
test_destructor();
test_swap();
Expand Down

0 comments on commit fd44ca3

Please sign in to comment.