bslstl_optional

Macros
#define	BSLSTL_OPTIONAL_IS_CONSTRUCTIBLE(U, V, DEFAULT)    std::is_constructible<U, V>::value
#define	BSLSTL_OPTIONAL_IS_ASSIGNABLE(U, V, DEFAULT)    std::is_assignable<U, V>::value
#define	BSLSTL_OPTIONAL_CONVERTS_FROM(TYPE, OPT_TYPE)
#define	BSLSTL_OPTIONAL_ASSIGNS_FROM(TYPE, OPT_TYPE)
#define	BSLSTL_OPTIONAL_CONVERTS_FROM_BSL_OPTIONAL(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_ASSIGNS_FROM_BSL_OPTIONAL(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_CONVERTS_FROM_STD_OPTIONAL(TYPE, ANY_TYPE)   false
#define	BSLSTL_OPTIONAL_ASSIGNS_FROM_STD_OPTIONAL(TYPE, ANY_TYPE)   false
#define	BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCTS_FROM_BSL_OPTIONAL(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCTS_FROM_BSL_OPTIONAL(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCTS_FROM_STD_OPTIONAL(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCTS_FROM_STD_OPTIONAL(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCT_PROPAGATES_ALLOCATOR(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCT_PROPAGATES_ALLOCATOR(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCT_DOES_NOT_PROPAGATE_ALLOCATOR( TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCT_DOES_NOT_PROPAGATE_ALLOCATOR( TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCTS_FROM(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCTS_FROM(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_DEFINE_IF_DERIVED_FROM_OPTIONAL(DERIVED)
#define	BSLSTL_OPTIONAL_DECLARE_IF_DERIVED_FROM_OPTIONAL(DERIVED)
#define	BSLSTL_OPTIONAL_DEFINE_IF_EXPLICIT_CONSTRUCT(U, V)
#define	BSLSTL_OPTIONAL_DECLARE_IF_EXPLICIT_CONSTRUCT(U, V)
#define	BSLSTL_OPTIONAL_DEFINE_IF_NOT_EXPLICIT_CONSTRUCT(U, V)
#define	BSLSTL_OPTIONAL_DECLARE_IF_NOT_EXPLICIT_CONSTRUCT(U, V)
#define	BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_BSL_OPTIONAL(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_STD_OPTIONAL(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_DERIVED(TYPE, DERIVED)
#define	BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_FORWARD_REF(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_ANY_TYPE(TYPE, ANY_TYPE)
#define	BSLSTL_OPTIONAL_ENABLE_IF_NOT_ALLOCATOR_TAG(ARG)
#define	BSLSTL_OPTIONAL_DEFAULT_TEMPLATE_ARG(ARG)
#define	BSLSTL_OPTIONAL_REQUIRES(EXPR)

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Sections:
  • Usage
  • Known limitations

Purpose

Provide a standard-compliant allocator aware optional type.

Classes

• bsl::optional: template class for optional objects

Canonical header: bsl_optional.h

Description

This component provides a template class, bsl::optional<TYPE>, that implements a notion of object that may or may not contain a TYPE value. This template class also provides an interface to check if the optional object contains a value or not, as well as a contextual conversion to bool. If an optional object is engaged, i.e. contains a value, it will evaluate to true when converted to bool; otherwise, it will evaluate to false when converted to bool.

An optional object is engaged if it has been initialized with, or assigned from an object of TYPE or another engaged optional object, or if the value was created using the emplace method. Other types of assignment and initialization (including default initialization), as well as calling reset method will result in the optional object being disengaged.

If the underlying TYPE has value-semantics, then so will the type bsl::optional<TYPE>. Two homogeneous optional objects have the same value if their underlying (non-null) TYPE values are the same, or both are null.

Note that the object of template parameter TYPE that is managed by a bsl::optional<TYPE> object is created in-*place*. Consequently, the template parameter TYPE must be a complete type when the class is instantiated.

In addition to the standard homogeneous, value-semantic, operations such as copy/move construction, copy/move assignment, equality comparison, and relational operators, bsl::optional also supports conversion between optional types for which the underlying types are convertible, i.e., for heterogeneous copy construction, copy assignment, and equality comparison (e.g., between int and double); attempts at conversion between incompatible types, such as int and bsl::string, will fail to compile.

For allocator-aware types, bsl::optional uses the same allocator for all value_type objects it manages during its lifetime.

Sections:

This file is very complex, a navigation map of this file can be obtained by: $ grep -n Section: bslstl_optional.h

Usage

The following snippets of code illustrate use of this component:

First, create a optional int object:

bsl::optional<int> optionalInt;
assert(!optionalInt.has_value());

Next, give the int object the value 123 (making it non-null):

optionalInt.emplace(123);
assert( optionalInt.has_value());
assert(123 == optionalInt.value());

Finally, reset the object to its default constructed state (i.e., null):

optionalInt.reset();
assert(!optionalInt.has_value());

Known limitations

• For assignment/construction constraints, we use is_constructible but the exact creation will be done using allocation construction that will invoke an allocator-extended constructor for allocator-aware types. If the value_type is constructible from the assignment/constructor argument, but doesn't have a corresponding allocator-extended constructor, the overload selection may not be be correct.
• optional<const TYPE> is fully supported in C++11 and onwards. However, due to limitations of MovableRef<const TYPE>, C++03 support for const value_types is limited and move semantics of such an optional in C++03 will not work.

Macro Definition Documentation

BSLSTL_OPTIONAL_ASSIGNS_FROM

#define BSLSTL_OPTIONAL_ASSIGNS_FROM	(		TYPE,
			OPT_TYPE
	)

Value:

    (std::is_assignable<TYPE&, const OPT_TYPE&>::value ||                     \
     std::is_assignable<TYPE&, OPT_TYPE&>::value ||                           \
     std::is_assignable<TYPE&, const OPT_TYPE>::value ||                      \
     std::is_assignable<TYPE&, OPT_TYPE>::value)

BSLSTL_OPTIONAL_ASSIGNS_FROM_BSL_OPTIONAL

#define BSLSTL_OPTIONAL_ASSIGNS_FROM_BSL_OPTIONAL	(		TYPE,
			ANY_TYPE
	)

Value:

    BSLSTL_OPTIONAL_ASSIGNS_FROM(                                             \
        TYPE,                                                                 \
        bsl::optional<typename bsl::remove_cvref<ANY_TYPE>::type>)

BSLSTL_OPTIONAL_ASSIGNS_FROM_STD_OPTIONAL

#define BSLSTL_OPTIONAL_ASSIGNS_FROM_STD_OPTIONAL	(		TYPE,
			ANY_TYPE
	)		false

BSLSTL_OPTIONAL_CONVERTS_FROM

#define BSLSTL_OPTIONAL_CONVERTS_FROM	(		TYPE,
			OPT_TYPE
	)

Value:

    (bsl::is_convertible<const OPT_TYPE&, TYPE>::value ||                     \
     bsl::is_convertible<OPT_TYPE&, TYPE>::value ||                           \
     bsl::is_convertible<const OPT_TYPE, TYPE>::value ||                      \
     bsl::is_convertible<OPT_TYPE, TYPE>::value ||                            \
     BSLSTL_OPTIONAL_IS_CONSTRUCTIBLE(TYPE, const OPT_TYPE&, false) ||      \
     BSLSTL_OPTIONAL_IS_CONSTRUCTIBLE(TYPE, OPT_TYPE&, false) ||            \
     BSLSTL_OPTIONAL_IS_CONSTRUCTIBLE(TYPE, const OPT_TYPE, false) ||       \
     BSLSTL_OPTIONAL_IS_CONSTRUCTIBLE(TYPE, OPT_TYPE, false))

BSLSTL_OPTIONAL_CONVERTS_FROM_BSL_OPTIONAL

#define BSLSTL_OPTIONAL_CONVERTS_FROM_BSL_OPTIONAL	(		TYPE,
			ANY_TYPE
	)

Value:

    BSLSTL_OPTIONAL_CONVERTS_FROM(                                            \
        TYPE,                                                                 \
        bsl::optional<typename bsl::remove_cvref<ANY_TYPE>::type>)

BSLSTL_OPTIONAL_CONVERTS_FROM_STD_OPTIONAL

#define BSLSTL_OPTIONAL_CONVERTS_FROM_STD_OPTIONAL	(		TYPE,
			ANY_TYPE
	)		false

BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCT_DOES_NOT_PROPAGATE_ALLOCATOR

#define BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCT_DOES_NOT_PROPAGATE_ALLOCATOR	(		TYPE,
			ANY_TYPE
	)

Value:

    BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCT_DOES_NOT_PROPAGATE_ALLOCATOR(         \
                     TYPE,                                                    \
                     ANY_TYPE) = BloombergLP::bslstl::Optional_OptNoSuchType(0)

BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCT_PROPAGATES_ALLOCATOR

#define BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCT_PROPAGATES_ALLOCATOR	(		TYPE,
			ANY_TYPE
	)

Value:

    BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCT_PROPAGATES_ALLOCATOR(                 \
                     TYPE,                                                    \
                     ANY_TYPE) = BloombergLP::bslstl::Optional_OptNoSuchType(0)

BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCTS_FROM

#define BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCTS_FROM	(		TYPE,
			ANY_TYPE
	)

Value:

    BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCTS_FROM(                                \
                     TYPE,                                                    \
                     ANY_TYPE) = BloombergLP::bslstl::Optional_OptNoSuchType(0)

BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCTS_FROM_BSL_OPTIONAL

#define BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCTS_FROM_BSL_OPTIONAL	(		TYPE,
			ANY_TYPE
	)

Value:

    BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCTS_FROM_BSL_OPTIONAL(                   \
                     TYPE,                                                    \
                     ANY_TYPE) = BloombergLP::bslstl::Optional_OptNoSuchType(0)

BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCTS_FROM_STD_OPTIONAL

#define BSLSTL_OPTIONAL_DECLARE_IF_CONSTRUCTS_FROM_STD_OPTIONAL	(		TYPE,
			ANY_TYPE
	)

Value:

    BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCTS_FROM_STD_OPTIONAL(                   \
                     TYPE,                                                    \
                     ANY_TYPE) = BloombergLP::bslstl::Optional_OptNoSuchType(0)

BSLSTL_OPTIONAL_DECLARE_IF_DERIVED_FROM_OPTIONAL

#define BSLSTL_OPTIONAL_DECLARE_IF_DERIVED_FROM_OPTIONAL

(

DERIVED

)

Value:

    BSLSTL_OPTIONAL_DEFINE_IF_DERIVED_FROM_OPTIONAL(DERIVED) =                \
                                 BloombergLP::bslstl::Optional_OptNoSuchType(0)

BSLSTL_OPTIONAL_DECLARE_IF_EXPLICIT_CONSTRUCT

#define BSLSTL_OPTIONAL_DECLARE_IF_EXPLICIT_CONSTRUCT	(		U,
			V
	)

Value:

    BSLSTL_OPTIONAL_DEFINE_IF_EXPLICIT_CONSTRUCT(                             \
                            U,                                                \
                            V) = BloombergLP::bslstl::Optional_OptNoSuchType(0)

BSLSTL_OPTIONAL_DECLARE_IF_NOT_EXPLICIT_CONSTRUCT

#define BSLSTL_OPTIONAL_DECLARE_IF_NOT_EXPLICIT_CONSTRUCT	(		U,
			V
	)

Value:

    BSLSTL_OPTIONAL_DEFINE_IF_NOT_EXPLICIT_CONSTRUCT(                         \
                            U,                                                \
                            V) = BloombergLP::bslstl::Optional_OptNoSuchType(0)

BSLSTL_OPTIONAL_DEFAULT_TEMPLATE_ARG

#define BSLSTL_OPTIONAL_DEFAULT_TEMPLATE_ARG

(

ARG

)

BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCT_DOES_NOT_PROPAGATE_ALLOCATOR

#define BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCT_DOES_NOT_PROPAGATE_ALLOCATOR	(		TYPE,
			ANY_TYPE
	)

Value:

    typename bsl::enable_if<                                                  \
        !BloombergLP::bslstl::Optional_PropagatesAllocator<TYPE,              \
                                                           ANY_TYPE>::value,  \
        BloombergLP::bslstl::Optional_OptNoSuchType>::type

BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCT_PROPAGATES_ALLOCATOR

#define BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCT_PROPAGATES_ALLOCATOR	(		TYPE,
			ANY_TYPE
	)

Value:

    typename bsl::enable_if<                                                  \
        BloombergLP::bslstl::Optional_PropagatesAllocator<TYPE,               \
                                                          ANY_TYPE>::value,   \
        BloombergLP::bslstl::Optional_OptNoSuchType>::type

BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCTS_FROM

#define BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCTS_FROM	(		TYPE,
			ANY_TYPE
	)

Value:

    typename bsl::enable_if<                                                  \
        BloombergLP::bslstl::Optional_ConstructsFromType<TYPE,                \
                                                         ANY_TYPE>::value,    \
        BloombergLP::bslstl::Optional_OptNoSuchType>::type

BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCTS_FROM_BSL_OPTIONAL

#define BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCTS_FROM_BSL_OPTIONAL	(		TYPE,
			ANY_TYPE
	)

Value:

    typename bsl::enable_if<                                                  \
        !bsl::is_same<TYPE, ANY_TYPE>::value &&                               \
        !BSLSTL_OPTIONAL_CONVERTS_FROM_BSL_OPTIONAL(TYPE, ANY_TYPE) &&        \
            BSLSTL_OPTIONAL_IS_CONSTRUCTIBLE(TYPE, ANY_TYPE, true),           \
        BloombergLP::bslstl::Optional_OptNoSuchType>::type

BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCTS_FROM_STD_OPTIONAL

#define BSLSTL_OPTIONAL_DEFINE_IF_CONSTRUCTS_FROM_STD_OPTIONAL	(		TYPE,
			ANY_TYPE
	)

Value:

    typename bsl::enable_if<                                                  \
        !BSLSTL_OPTIONAL_CONVERTS_FROM_STD_OPTIONAL(TYPE, ANY_TYPE) &&        \
            BSLSTL_OPTIONAL_IS_CONSTRUCTIBLE(TYPE, ANY_TYPE, true),           \
        BloombergLP::bslstl::Optional_OptNoSuchType>::type

BSLSTL_OPTIONAL_DEFINE_IF_DERIVED_FROM_OPTIONAL

#define BSLSTL_OPTIONAL_DEFINE_IF_DERIVED_FROM_OPTIONAL

(

DERIVED

)

Value:

    typename bsl::enable_if<                                                  \
        BloombergLP::bslmf::IsAccessibleBaseOf<optional, DERIVED>::value &&   \
        !bsl::is_const<DERIVED>::value,                                       \
        BloombergLP::bslstl::Optional_OptNoSuchType>::type

BSLSTL_OPTIONAL_DEFINE_IF_EXPLICIT_CONSTRUCT

#define BSLSTL_OPTIONAL_DEFINE_IF_EXPLICIT_CONSTRUCT	(		U,
			V
	)

Value:

    typename bsl::enable_if<                                                  \
        !bsl::is_convertible<V, U>::value,                                    \
        BloombergLP::bslstl::Optional_OptNoSuchType>::type

BSLSTL_OPTIONAL_DEFINE_IF_NOT_EXPLICIT_CONSTRUCT

#define BSLSTL_OPTIONAL_DEFINE_IF_NOT_EXPLICIT_CONSTRUCT	(		U,
			V
	)

Value:

    typename bsl::enable_if<                                                  \
        bsl::is_convertible<V, U>::value,                                     \
        BloombergLP::bslstl::Optional_OptNoSuchType>::type

BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_ANY_TYPE

#define BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_ANY_TYPE	(		TYPE,
			ANY_TYPE
	)

Value:

    typename bsl::enable_if<                                                  \
        !::BloombergLP::bslmf::IsAccessibleBaseOf<                            \
            bsl::optional<TYPE>,                                              \
            typename bsl::remove_cv<                                          \
                typename ::BloombergLP::bslmf::MovableRefUtil::               \
                    RemoveReference<ANY_TYPE>::type>::type>::value,           \
        optional<TYPE> >::type

BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_BSL_OPTIONAL

#define BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_BSL_OPTIONAL	(		TYPE,
			ANY_TYPE
	)

Value:

    typename bsl::enable_if<                                                  \
        !BSLSTL_OPTIONAL_CONVERTS_FROM_BSL_OPTIONAL(TYPE, ANY_TYPE) &&        \
            BSLSTL_OPTIONAL_IS_CONSTRUCTIBLE(TYPE, ANY_TYPE, true) &&         \
            BSLSTL_OPTIONAL_IS_ASSIGNABLE(TYPE&, ANY_TYPE, true) &&           \
            !BSLSTL_OPTIONAL_ASSIGNS_FROM_BSL_OPTIONAL(TYPE, ANY_TYPE),       \
        optional<TYPE> >::type

BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_DERIVED

#define BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_DERIVED	(		TYPE,
			DERIVED
	)

Value:

      typename bsl::enable_if<                                                \
        BloombergLP::bslmf::IsAccessibleBaseOf<bsl::optional<TYPE>,           \
                                               DERIVED>::value &&             \
        !bsl::is_same<bsl::optional<TYPE>, DERIVED>::value,                   \
        optional<TYPE> >::type

BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_FORWARD_REF

#define BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_FORWARD_REF	(		TYPE,
			ANY_TYPE
	)

Value:

    typename bsl::enable_if<                                                  \
        !bsl::is_same<bsl::optional<TYPE>,                                    \
                      typename bsl::remove_cvref<ANY_TYPE>::type>::value &&   \
            !(bsl::is_same<TYPE,                                              \
                           typename bsl::decay<ANY_TYPE>::type>::value &&     \
              std::is_scalar<TYPE>::value) &&                                 \
            std::is_constructible<TYPE, ANY_TYPE>::value &&                   \
            std::is_assignable<TYPE, ANY_TYPE>::value,                        \
        optional<TYPE> >::type

BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_STD_OPTIONAL

#define BSLSTL_OPTIONAL_ENABLE_ASSIGN_FROM_STD_OPTIONAL	(		TYPE,
			ANY_TYPE
	)

Value:

    typename bsl::enable_if<                                                  \
        !BSLSTL_OPTIONAL_CONVERTS_FROM_STD_OPTIONAL(TYPE, ANY_TYPE) &&        \
            BSLSTL_OPTIONAL_IS_CONSTRUCTIBLE(TYPE, ANY_TYPE, true) &&         \
            BSLSTL_OPTIONAL_IS_ASSIGNABLE(TYPE&, ANY_TYPE, true) &&           \
            !BSLSTL_OPTIONAL_ASSIGNS_FROM_STD_OPTIONAL(TYPE, ANY_TYPE),       \
        optional<TYPE> >::type

BSLSTL_OPTIONAL_ENABLE_IF_NOT_ALLOCATOR_TAG

#define BSLSTL_OPTIONAL_ENABLE_IF_NOT_ALLOCATOR_TAG

(

ARG

)

Value:

    typename bsl::enable_if<                                                  \
        !bsl::is_same<                                                        \
            typename bsl::remove_cvref<ARG>::type,                            \
            bsl::allocator_arg_t>::value,                                     \
        optional<t_TYPE> >::type

BSLSTL_OPTIONAL_IS_ASSIGNABLE

#define BSLSTL_OPTIONAL_IS_ASSIGNABLE	(		U,
			V,
			DEFAULT
	)		std::is_assignable<U, V>::value

BSLSTL_OPTIONAL_IS_CONSTRUCTIBLE

#define BSLSTL_OPTIONAL_IS_CONSTRUCTIBLE	(		U,
			V,
			DEFAULT
	)		std::is_constructible<U, V>::value

BSLSTL_OPTIONAL_REQUIRES

#define BSLSTL_OPTIONAL_REQUIRES

(

EXPR

)