1[/ 2Copyright 2020 Glen Joseph Fernandes 3(glenjofe@gmail.com) 4 5Distributed under the Boost Software License, Version 1.0. 6(http://www.boost.org/LICENSE_1_0.txt) 7] 8 9[section Allocator Access] 10 11[simplesect Authors] 12 13* Glen Fernandes 14 15[endsimplesect] 16 17[section Overview] 18 19The header `<boost/core/allocator_access.hpp>` provides the class and function 20templates to simplify allocator use. It provides the same functionality as the 21C++ standard library `std::allocator_traits` but with individual templates for 22each allocator feature. 23 24These facilities also simplify existing libraries by avoiding having to check 25for `BOOST_NO_CXX11_ALLOCATOR` and conditionally use `std::allocator_traits`. 26 27[endsect] 28 29[section Examples] 30 31The following example shows these utilities used in the definition of 32an allocator-aware container class: 33 34``` 35template<class T, class A = boost::default_allocator<T> > 36class container 37 : boost::empty_value<typename boost::allocator_rebind<A, T>::type> { 38public: 39 typedef T value_type; 40 typedef A allocator_type; 41 typedef typename boost::allocator_size_type<A>::type size_type; 42 typedef typename boost::allocator_difference_type<A>::type difference_type; 43 typedef value_type& reference; 44 typedef const value_type& const_reference; 45 typedef typename boost::allocator_pointer<A>::type pointer; 46 typedef typename boost::allocator_const_pointer<A>::type const_pointer; 47 // ... 48}; 49``` 50 51In C++11 or above, aliases such as `boost::allocator_pointer_t<A>` can be used 52instead of `typename boost::allocator_pointer<A>::type`. 53 54[endsect] 55 56[section Reference] 57 58``` 59namespace boost { 60 61template<class A> 62struct allocator_value_type; 63 64template<class A> 65using allocator_value_type_t = typename allocator_value_type<A>::type; 66 67template<class A> 68struct allocator_pointer; 69 70template<class A> 71using allocator_pointer_t = typename allocator_pointer<A>::type; 72 73template<class A> 74struct allocator_const_pointer; 75 76template<class A> 77using allocator_const_pointer_t = typename allocator_const_pointer<A>::type; 78 79template<class A> 80struct allocator_void_pointer; 81 82template<class A> 83using allocator_void_pointer_t = typename allocator_void_pointer<A>::type; 84 85template<class A> 86struct allocator_const_void_pointer; 87 88template<class A> 89using allocator_const_void_pointer_t = 90 typename allocator_const_void_pointer<A>::type; 91 92template<class A> 93struct allocator_difference_type; 94 95template<class A> 96using allocator_difference_type_t = 97 typename allocator_difference_type<A>::type; 98 99template<class A> 100struct allocator_size_type; 101 102template<class A> 103using allocator_size_type_t = typename allocator_size_type<A>::type; 104 105template<class A> 106struct allocator_propagate_on_container_copy_assignment; 107 108template<class A> 109using allocator_propagate_on_container_copy_assignment_t = 110 typename allocator_propagate_on_container_copy_assignment<A>::type; 111 112template<class A> 113struct allocator_propagate_on_container_move_assignment; 114 115template<class A> 116using allocator_propagate_on_container_move_assignment_t = 117 typename allocator_propagate_on_container_move_assignment<A>::type; 118 119template<class A> 120struct allocator_propagate_on_container_swap; 121 122template<class A> 123using allocator_propagate_on_container_swap_t = 124 typename allocator_propagate_on_container_swap<A>::type; 125 126template<class A> 127struct allocator_is_always_equal; 128 129template<class A> 130using allocator_is_always_equal_t = 131 typename allocator_is_always_equal<A>::type; 132 133template<class A, class T> 134struct allocator_rebind; 135 136template<class A, class T> 137using allocator_rebind_t = typename allocator_rebind<A, T>::type; 138 139template<class A> 140allocator_pointer_t<A> allocator_allocate(A& a, allocator_size_type_t<A> n); 141 142template<class A> 143allocator_pointer_t<A> allocator_allocate(A& a, allocator_size_type_t<A> n, 144 allocator_const_void_pointer_t<A> h); 145 146template<class A> 147void allocator_deallocate(A& a, allocator_pointer_t<A> p, 148 allocator_size_type_t<A> n); 149 150template<class A, class T, class... Args> 151void allocator_construct(A& a, T* p, Args&&... args); 152 153template<class A, class T> 154void allocator_destroy(A& a, T* p); 155 156template<class A> 157allocator_size_type_t<A> allocator_max_size(const A& a); 158 159template<class A> 160A allocator_select_on_container_copy_construction(const A& a); 161 162} // boost 163``` 164 165[section Types] 166 167[variablelist 168[[`template<class A> struct allocator_value_type;`] 169[The member `type` is `A::value_type`.]] 170[[`template<class A> struct allocator_pointer;`] 171[The member `type` is `A::pointer` if valid, otherwise `A::value_type*`.]] 172[[`template<class A> struct allocator_const_pointer;`] 173[The member `type` is `A::const_pointer` if valid, otherwise 174`pointer_traits<allocator_pointer_t<A> >::rebind<const 175allocator_value_type_t<A> >`.]] 176[[`template<class A> struct allocator_void_pointer;`] 177[The member `type` is `A::void_pointer` if valid, otherwise 178`pointer_traits<allocator_pointer_t<A> >::rebind<void>`.]] 179[[`template<class A> struct allocator_const_void_pointer;`] 180[The member `type` is `A::const_void_pointer` if valid, otherwise 181`pointer_traits<allocator_pointer_t<A> >::rebind<const void>`.]] 182[[`template<class A> struct allocator_difference_type;`] 183[The member `type` is `A::difference_type` if valid, otherwise 184`pointer_traits<allocator_pointer_t<A> >::difference_type`.]] 185[[`template<class A> struct allocator_size_type;`] 186[The member `type` is `A::size_type` if valid, otherwise 187`std::make_unsigned_t<allocator_difference_type_t<A> >`.]] 188[[`template<class A> struct allocator_propagate_on_container_copy_assignment;`] 189[The member `type` is `A::propagate_on_container_copy_assignment` if valid, 190otherwise `std::false_type`.]] 191[[`template<class A> struct allocator_propagate_on_container_move_assignment;`] 192[The member `type` is `A::propagate_on_container_move_assignment` if valid, 193otherwise `std::false_type`.]] 194[[`template<class A> struct allocator_propagate_on_container_swap;`] 195[The member `type` is `A::propagate_on_container_swap` if valid, otherwise 196`std::false_type`.]] 197[[`template<class A> struct allocator_is_always_equal;`] 198[The member `type` is `A::is_always_equal` if valid, otherwise 199`std::is_empty<A>::type`.]] 200[[`template<class A, class T> struct allocator_rebind;`] 201[The member `type` is `A::rebind<T>::other` if valid, otherwise `A<T, Args>` 202if this `A` is `A<U, Args>`.]]] 203 204[endsect] 205 206[section Functions] 207 208[variablelist 209[[`template<class A> 210allocator_pointer_t<A> allocator_allocate(A& a, allocator_size_type_t<A> n);`] 211[Calls `a.allocate(n)`.]] 212[[`template<class A> allocator_pointer_t<A> allocator_allocate(A& a, 213allocator_size_type_t<A> n, allocator_const_void_pointer_t<A> hint);`] 214[Calls `a.allocate(n, hint)` if valid, otherwise calls `a.allocate(n)`.]] 215[[`template<class A> void allocator_deallocate(A& a, allocator_pointer_t<A> p, 216allocator_size_type_t<A> n);`] 217[Calls `a.deallocate(p, n)`.]] 218[[`template<class A, class T, class... Args> 219void allocator_construct(A& a, T*p, Args&&... args);`] 220[Calls `a.construct(p, std::forward<Args>(args)...)` if valid, otherwise calls 221`::new(static_cast<void*>(p)) T(std::forward<Args>(args)...)`.]] 222[[`template<class A, class T> void allocator_destroy(A& a, T* p);`] 223[Calls `a.destroy(p)` if valid, otherwise calls `p->~T()`.]] 224[[`template<class A> allocator_size_type_t<A> allocator_max_size(const A& a);`] 225[Returns `a.max_size()` if valid, otherwise returns 226`std::numeric_limits<allocator_size_type_t<A> >::max() / 227sizeof(A::value_type)`.]] 228[[`template<class A> A allocator_select_on_container_copy_construction(const 229A& a);`] 230[Returns `a.select_on_container_copy_construction()` if valid, otherwise 231returns `a`.]]] 232 233[endsect] 234 235[endsect] 236 237[section Acknowledgments] 238 239Glen Fernandes implemented the allocator access utilities. 240 241[endsect] 242 243[endsect] 244