| Home | Libraries | People | FAQ | More

## Class template scoped_allocator_adaptor

boost::container::scoped_allocator_adaptor

## Synopsis

    // In header: <boost/container/scoped_allocator.hpp>

    template<typename OuterAlloc, typename... InnerAllocs>
    class scoped_allocator_adaptor :
      public dtl::scoped_allocator_adaptor_base< OuterAlloc, InnerAllocs...>
    {
    public:
      // types
      typedef OuterAlloc                                        outer_allocator_type;
      typedef allocator_traits< OuterAlloc >                    outer_traits_type;
      typedef base_type::inner_allocator_type                   inner_allocator_type;
      typedef allocator_traits< inner_allocator_type >          inner_traits_type;
      typedef outer_traits_type::value_type                     value_type;
      typedef outer_traits_type::size_type                      size_type;
      typedef outer_traits_type::difference_type                difference_type;
      typedef outer_traits_type::pointer                        pointer;
      typedef outer_traits_type::const_pointer                  const_pointer;
      typedef outer_traits_type::void_pointer                   void_pointer;
      typedef outer_traits_type::const_void_pointer             const_void_pointer;
      typedef base_type::propagate_on_container_copy_assignment propagate_on_container_copy_assignment;
      typedef base_type::propagate_on_container_move_assignment propagate_on_container_move_assignment;
      typedef base_type::propagate_on_container_swap            propagate_on_container_swap;
      typedef base_type::is_always_equal                        is_always_equal;

      // member classes/structs/unions
      template<typename U>
      struct rebind {
        // types
        typedef scoped_allocator_adaptor< typename outer_traits_type::template portable_rebind_alloc< U >::type, InnerAllocs...> other;
      };

      // construct/copy/destruct
      scoped_allocator_adaptor();
      scoped_allocator_adaptor(const scoped_allocator_adaptor &);
      scoped_allocator_adaptor(scoped_allocator_adaptor &&);
      template<typename OuterA2>
        scoped_allocator_adaptor(OuterA2 &&, const InnerAllocs &...);
      template<typename OuterA2>
        scoped_allocator_adaptor(const scoped_allocator_adaptor< OuterA2, InnerAllocs...> &);
      template<typename OuterA2>
        scoped_allocator_adaptor(scoped_allocator_adaptor< OuterA2, InnerAllocs...> &&);
      scoped_allocator_adaptor & operator=(const scoped_allocator_adaptor &);
      scoped_allocator_adaptor & operator=(scoped_allocator_adaptor &&);
      ~scoped_allocator_adaptor();

      // public member functions
      void swap(scoped_allocator_adaptor &);
      outer_allocator_type & outer_allocator() noexcept;
      const outer_allocator_type & outer_allocator() const noexcept;
      inner_allocator_type & inner_allocator() noexcept;
      inner_allocator_type const & inner_allocator() const noexcept;
      size_type max_size() const noexcept;
      template<typename T> void destroy(T *) noexcept;
      pointer allocate(size_type);
      pointer allocate(size_type, const_void_pointer);
      void deallocate(pointer, size_type);
      scoped_allocator_adaptor select_on_container_copy_construction() const;
      template<typename T, class... Args> void construct(T *, Args &&...);

      // friend functions
      friend void swap(scoped_allocator_adaptor &, scoped_allocator_adaptor &);
    };

## Description

This class is a C++03-compatible implementation of std::scoped_allocator_adaptor. The class template scoped_allocator_adaptor is an allocator template that specifies the memory resource (the outer allocator) to be used by a container (as any other allocator does) and also specifies an inner allocator resource to be passed to the constructor of every element within the container.

This adaptor is instantiated with one outer and zero or more inner allocator types. If instantiated with only one allocator type, the inner allocator becomes the scoped_allocator_adaptor itself, thus using the same allocator resource for the container and every element within the container and, if the elements themselves are containers, each of their elements recursively. If instantiated with more than one allocator, the first allocator is the outer allocator for use by the container, the second allocator is passed to the constructors of the container's elements, and, if the elements themselves are containers, the third allocator is passed to the elements' elements, and so on. If containers are nested to a depth greater than the number of allocators, the last allocator is used repeatedly, as in the single-allocator case, for any remaining recursions.

[Note: The scoped_allocator_adaptor is derived from the outer allocator type so it can be substituted for the outer allocator type in most expressions. -end note]

In the construct member functions, `OUTERMOST(x)` is x if x does not have an `outer_allocator()` member function and `OUTERMOST(x.outer_allocator())` otherwise; `OUTERMOST_ALLOC_TRAITS(x)` is `allocator_traits<decltype(OUTERMOST(x))>`.

[Note: `OUTERMOST(x)` and `OUTERMOST_ALLOC_TRAITS(x)` are recursive operations. It is incumbent upon the definition of `outer_allocator()` to ensure that the recursion terminates. It will terminate for all instantiations of scoped_allocator_adaptor. -end note]

### `scoped_allocator_adaptor` public types

1. typedef allocator_traits< OuterAlloc > outer_traits_type;

   Type: For exposition only

2. typedef base_type::inner_allocator_type inner_allocator_type;

   Type: `scoped_allocator_adaptor<OuterAlloc>` if `sizeof...(InnerAllocs)` is zero; otherwise, `scoped_allocator_adaptor<InnerAllocs...>`.

3. typedef base_type::propagate_on_container_copy_assignment propagate_on_container_copy_assignment;

   Type: A type with a constant boolean `value` == true if `allocator_traits<Allocator>:: propagate_on_container_copy_assignment::value` is true for any `Allocator` in the set of `OuterAlloc` and `InnerAllocs...`, false otherwise.

4. typedef base_type::propagate_on_container_move_assignment propagate_on_container_move_assignment;

   Type: A type with a constant boolean `value` == true if `allocator_traits<Allocator>:: propagate_on_container_move_assignment::value` is true for any `Allocator` in the set of `OuterAlloc` and `InnerAllocs...`, false otherwise.

5. typedef base_type::propagate_on_container_swap propagate_on_container_swap;

   Type: A type with a constant boolean `value` == true if `allocator_traits<Allocator>:: propagate_on_container_swap::value` is true for any `Allocator` in the set of `OuterAlloc` and `InnerAllocs...`, false otherwise.

6. typedef base_type::is_always_equal is_always_equal;

   Type: A type with a constant boolean `value` == true if `allocator_traits<Allocator>:: is_always_equal::value` is true for all `Allocator` in the set of `OuterAlloc` and `InnerAllocs...`, false otherwise.

### `scoped_allocator_adaptor` public construct/copy/destruct

1.     scoped_allocator_adaptor();

   Effects: value-initializes the OuterAlloc base class and the inner allocator object.

2.     scoped_allocator_adaptor(const scoped_allocator_adaptor & other);

   Effects: initializes each allocator within the adaptor with the corresponding allocator from other.

3.     scoped_allocator_adaptor(scoped_allocator_adaptor && other);

   Effects: move constructs each allocator within the adaptor with the corresponding allocator from other.

4.     template<typename OuterA2>
         scoped_allocator_adaptor(OuterA2 && outerAlloc,
                                  const InnerAllocs &... innerAllocs);

   Requires: OuterAlloc shall be constructible from OuterA2.

   Effects: initializes the OuterAlloc base class with boost::forward<OuterA2>(outerAlloc) and inner with innerAllocs...(hence recursively initializing each allocator within the adaptor with the corresponding allocator from the argument list).

5.     template<typename OuterA2>
         scoped_allocator_adaptor(const scoped_allocator_adaptor< OuterA2, InnerAllocs...> & other);

   Requires: OuterAlloc shall be constructible from OuterA2.

   Effects: initializes each allocator within the adaptor with the corresponding allocator from other.

6.     template<typename OuterA2>
         scoped_allocator_adaptor(scoped_allocator_adaptor< OuterA2, InnerAllocs...> && other);

   Requires: OuterAlloc shall be constructible from OuterA2.

   Effects: initializes each allocator within the adaptor with the corresponding allocator rvalue from other.

7.     scoped_allocator_adaptor & operator=(const scoped_allocator_adaptor & other);

8.     scoped_allocator_adaptor & operator=(scoped_allocator_adaptor && other);

9.     ~scoped_allocator_adaptor();

### `scoped_allocator_adaptor` public member functions

1.     void swap(scoped_allocator_adaptor & r);

   Effects: swaps *this with r.

2.     outer_allocator_type & outer_allocator() noexcept;

   Returns: `static_cast<OuterAlloc&>(*this)`.

3.     const outer_allocator_type & outer_allocator() const noexcept;

   Returns: `static_cast<const OuterAlloc&>(*this)`.

4.     inner_allocator_type & inner_allocator() noexcept;

   Returns: *this if `sizeof...(InnerAllocs)` is zero; otherwise, inner.

5.     inner_allocator_type const & inner_allocator() const noexcept;

   Returns: *this if `sizeof...(InnerAllocs)` is zero; otherwise, inner.

6.     size_type max_size() const noexcept;

   Returns: `allocator_traits<OuterAlloc>:: max_size(outer_allocator())`.

7.     template<typename T> void destroy(T * p) noexcept;

   Effects: calls `OUTERMOST_ALLOC_TRAITS(*this):: destroy(OUTERMOST(*this), p)`.

8.     pointer allocate(size_type n);

   Returns: `allocator_traits<OuterAlloc>::allocate(outer_allocator(), n)`.

9.     pointer allocate(size_type n, const_void_pointer hint);

   Returns: `allocator_traits<OuterAlloc>::allocate(outer_allocator(), n, hint)`.

10.     void deallocate(pointer p, size_type n);

    Effects: `allocator_traits<OuterAlloc>::deallocate(outer_allocator(), p, n)`.

11.     scoped_allocator_adaptor select_on_container_copy_construction() const;

    Returns: A new `scoped_allocator_adaptor` object where each allocator Allocator in the adaptor is initialized from the result of calling `allocator_traits<Allocator>::select_on_container_copy_construction()` on the corresponding allocator in *this.

12.     template<typename T, class... Args> void construct(T * p, Args &&... args);

    Effects: 1) If `uses_allocator<T, inner_allocator_type>::value` is false calls `OUTERMOST_ALLOC_TRAITS(*this):: construct(OUTERMOST(*this), p, std::forward<Args>(args)...)`.

    2) Otherwise, if `uses_allocator<T, inner_allocator_type>::value` is true and `is_constructible<T, allocator_arg_t, inner_allocator_type, Args...>:: value` is true, calls `OUTERMOST_ALLOC_TRAITS(*this):: construct(OUTERMOST(*this), p, allocator_arg, inner_allocator(), std::forward<Args>(args)...)`.

    [Note: In compilers without advanced decltype SFINAE support, `is_constructible` can't be implemented so that condition will be replaced by constructible_with_allocator_prefix<T>::value. -end note]

    3) Otherwise, if uses_allocator<T, inner_allocator_type>::value is true and `is_constructible<T, Args..., inner_allocator_type>:: value` is true, calls `OUTERMOST_ALLOC_TRAITS(*this):: construct(OUTERMOST(*this), p, std::forward<Args>(args)..., inner_allocator())`.

    [Note: In compilers without advanced decltype SFINAE support, `is_constructible` can't be implemented so that condition will be replaced by `constructible_with_allocator_suffix<T>:: value`. -end note]

    4) Otherwise, the program is ill-formed.

    [Note: An error will result if ``uses_allocator`` evaluates to true but the specific constructor does not take an allocator. This definition prevents a silent failure to pass an inner allocator to a contained element. -end note]

### `scoped_allocator_adaptor` friend functions

1.     friend void swap(scoped_allocator_adaptor & l, scoped_allocator_adaptor & r);

   Effects: swaps *this with r.