| Home | Libraries | People | FAQ | More

## Reference

### Functions

#### align

`void* align(std::size_t alignment, std::size_t size, void*& ptr, std::size_t& space);`

Header
  `#include <boost/align/align.hpp>`
Effects

  If it is possible to fit `size` bytes of storage aligned by `alignment` into the buffer pointed to by `ptr` with length `space`, the function updates `ptr` to point to the first possible address of such storage and decreases `space` by the number of bytes used for alignment. Otherwise, the function does nothing.

Requires
  - `alignment` shall be a power of two
  - `ptr` shall point to contiguous storage of at least `space` bytes
Returns
  A null pointer if the requested aligned buffer would not fit into the available space, otherwise the adjusted value of `ptr`.
Note

  The function updates its `ptr` and `space` arguments so that it can be called repeatedly with possibly different `alignment` and `size` arguments for the same buffer.

#### align_up

`constexpr std::size_t align_up(std::size_t value, std::size_t alignment) noexcept;`

Header

  `#include <boost/align/align_up.hpp>`

Requires

  `alignment` shall be a power of two

Returns

  A value at or after `value` that is a multiple of `alignment`.

#### align_down

`constexpr std::size_t align_down(std::size_t value, std::size_t alignment) noexcept;`

Header

  `#include <boost/align/align_down.hpp>`

Requires

  `alignment` shall be a power of two

Returns

  A value at or before `value` that is a multiple of `alignment`.

#### aligned_alloc

`void* aligned_alloc(std::size_t alignment, std::size_t size);`

Header

  `#include <boost/align/aligned_alloc.hpp>`

Effects

  Allocates space for an object whose alignment is specified by `alignment`, whose size is specified by `size`, and whose value is indeterminate.

Requires

  `alignment` shall be a power of two.

Returns

  A null pointer or a pointer to the allocated space.

Note

  On certain platforms, the space allocated may be slightly larger than `size` bytes, to allow for alignment.

#### aligned_free

`void aligned_free(void* ptr);`

Header

  `#include <boost/align/aligned_alloc.hpp>`

Effects

  Causes the space pointed to by `ptr` to be deallocated, that is, made available for further allocation. If `ptr` is a null pointer, no action occurs. Otherwise, if the argument does not match a pointer earlier returned by the `aligned_alloc()` function, or if the space has been deallocated by a call to `aligned_free()`, the behavior is undefined.

Requires

  `ptr` is a null pointer or a pointer earlier returned by the `aligned_alloc()` function that has not been deallocated by a call to `aligned_free()`.

Returns

  The `aligned_free()` function returns no value.

#### is_aligned

`bool is_aligned(const void* ptr, std::size_t alignment) noexcept;`

`constexpr bool is_aligned(std::size_t value, std::size_t alignment) noexcept;`

Header

  `#include <boost/align/is_aligned.hpp>`

Requires

  `alignment` shall be a power of two.

Returns

  `true` if the value of the first argument is aligned on the boundary specified by `alignment`, otherwise `false`.

### Classes

#### aligned_allocator

`template<class T, std::size_t Alignment = 1> class aligned_allocator;`

`template<std::size_t Alignment> class aligned_allocator<void, Alignment>;`

Header

  `#include <boost/align/aligned_allocator.hpp>`

Note

  Using the aligned allocator with a minimum Alignment value is generally only useful with containers that are not node-based such as `vector`. With node-based containers, such as `list`, the node object would have the minimum alignment instead of the value type object.

###### Member types

1. `typedef T value_type;`
2. `typedef T* pointer;`
3. `typedef const T* const_pointer;`
4. `typedef void* void_pointer;`
5. `typedef const void* const_void_pointer;`
6. `typedef std::size_t size_type;`
7. `typedef std::ptrdiff_t difference_type;`
8. `typedef T& reference;`
9. `typedef const T& const_reference;`
10. `template<class U> struct rebind { typedef aligned_allocator<U, Alignment> other; };`

###### Constructors

1. `aligned_allocator() = default;`

   Effects

     Constructs the allocator.

2. `template<class U> aligned_allocator(const aligned_allocator<U, Alignment>&) noexcept;`

   Effects

     Constructs the allocator.

###### Member functions

Except for the destructor, member functions of the aligned allocator shall not introduce data races as a result of concurrent calls to those member functions from different threads. Calls to these functions that allocate or deallocate a particular unit of storage shall occur in a single total order, and each such deallocation call shall happen before the next allocation (if any) in this order.

1. `pointer address(reference value) const noexcept;`

   Returns

     The actual address of the object referenced by `value`, even in the presence of an overloaded `operator&`.

2. `const_pointer address(const_reference value) const noexcept;`

   Returns

     The actual address of the object referenced by `value`, even in the presence of an overloaded `operator&`.

3. `pointer allocate(size_type size, const_void_pointer = 0);`

   Returns

     A pointer to the initial element of an array of storage of size `n * sizeof(T)`, aligned on the maximum of the minimum alignment specified and the alignment of objects of type `T`.

   Remark

     The storage is obtained by calling `aligned_alloc(std::size_t, std::size_t)`.

   Throws

     `std::bad_alloc` if the storage cannot be obtained.

4. `void deallocate(pointer ptr, size_type);`

   Requires

     `ptr` shall be a pointer value obtained from `allocate()`.

   Effects

     Deallocates the storage referenced by `ptr`.

   Remark

     Uses `aligned_free(void*)`.

5. `size_type max_size() const noexcept;`

   Returns

     The largest value `N` for which the call `allocate(N)` might succeed.

6. `template<class U, class... Args> void construct(U* ptr, Args&&... args);`

   Effects

     `::new((void*)ptr) U(std::forward<Args>(args)...)`.

7. `template<class U> void destroy(U* ptr);`

   Effects

     `ptr->~U()`.

###### Global operators

1. `template<class T1, class T2, std::size_t Alignment> bool operator==(const aligned_allocator<T1, Alignment>&, const aligned_allocator<T2, Alignment>&) noexcept;`

   Returns

     `true`

2. `template<class T1, class T2, std::size_t Alignment> bool operator!=(const aligned_allocator<T1, Alignment>&, const aligned_allocator<T2, Alignment>&) noexcept;`

   Returns

     `false`

#### aligned_allocator_adaptor

`template<class Allocator, std::size_t Alignment = 1> class aligned_allocator_adaptor;`

Header
  `#include <boost/align/aligned_allocator_adaptor.hpp>`
Note

  This adaptor can be used with a C++11 Allocator whose pointer type is a smart pointer but the adaptor can choose to expose only raw pointer types.

###### Member types

1. `typedef typename Allocator::value_type value_type;`
2. `typedef value_type* pointer;`
3. `typedef const value_type* const_pointer;`
4. `typedef void* void_pointer;`
5. `typedef const void* const_void_pointer;`
6. `typedef std::size_t size_type;`
7. `typedef std::ptrdiff_t difference_type;`
8. `template<class U> struct rebind { typedef aligned_allocator_adaptor<typename std::allocator_traits<Allocator>::template rebind_alloc<U>, Alignment> other; };`

###### Constructors

1. `aligned_allocator_adaptor() = default;`

   Effects

     Value-initializes the `Allocator` base class.

2. `template<class A> aligned_allocator_adaptor(A&& alloc) noexcept;`

   Requires

     `Allocator` shall be constructible from `A`.

   Effects

     Initializes the `Allocator` base class with `std::forward<A>(alloc)`.

3. `template<class U> aligned_allocator_adaptor(const aligned_allocator_adaptor<U, Alignment>& other) noexcept;`

   Requires

     `Allocator` shall be constructible from `A`.

   Effects

     Initializes the `Allocator` base class with `other.base()`.

###### Member functions

1. `Allocator& base() noexcept;`

   Returns

     `static_cast<Allocator&>(*this)`

2. `const Allocator& base() const noexcept;`

   Returns

     `static_cast<const Allocator&>(*this)`

3. `pointer allocate(size_type size);`

   Returns

     A pointer to the initial element of an array of storage of size `n * sizeof(value_type)`, aligned on the maximum of the minimum alignment specified and the alignment of objects of type `value_type`.

   Remark

     The storage is obtained by calling `A2::allocate()` on an object `a2`, where `a2` of type `A2` is a rebind copy of `base()` where its `value_type` is implementation defined.

   Throws

     Throws an exception thrown from `A2::allocate()` if the storage cannot be obtained.

4. `pointer allocate(size_type size, const_void_pointer hint);`

   Requires

     `hint` is a value obtained by calling `allocate()` on any equivalent allocator object, or else a null pointer.

   Returns

     A pointer to the initial element of an array of storage of size `n * sizeof(value_type)`, aligned on the maximum of the minimum alignment specified and the alignment of objects of type `value_type`.

   Remark

     The storage is obtained by calling `A2::allocate()` on an object `a2`, where `a2` of type `A2` is a rebind copy of `base()` where its `value_type` is an implementation defined.

   Throws

     Throws an exception thrown from `A2::allocate()` if the storage cannot be obtained.

5. `void deallocate(pointer ptr, size_type size);`

   Requires
     - `ptr` shall be a pointer value obtained from `allocate()`
     - `size` shall equal the value passed as the first argument to the invocation of `allocate()` which returned `ptr`.
   Effects
     Deallocates the storage referenced by `ptr`.
   Note

     Uses `A2::deallocate()` on an object `a2`, where `a2` of type `A2` is a rebound copy of `base()` where its `value_type` is implementation defined.

###### Global operators

1. `template<class A1, class A2, std::size_t Alignment> bool operator==(const aligned_allocator_adaptor<A1, Alignment>& a1, const aligned_allocator_adaptor<A2, Alignment>& a2) noexcept;`

   Returns

     `a1.base() == a2.base()`

2. `template<class A1, class A2, std::size_t Alignment> bool operator!=(const aligned_allocator_adaptor<A1, Alignment>& a1, const aligned_allocator_adaptor<A2, Alignment>& a2) noexcept;`

   Returns

     `!(a1 == a2)`

#### aligned_delete

`class aligned_delete;`

Header
  `#include <boost/align/aligned_delete.hpp>`

###### Member operators

1. `template<class T> void operator()(T* ptr) noexcept(noexcept(ptr->~T()));`

   Effects

     Calls `~T()` on `ptr` to destroy the object and then calls `aligned_free()` on `ptr` to free the allocated memory.

   Note

     If `T` is an incomplete type, the program is ill-formed.

### Traits

#### alignment_of

`template<class T> struct alignment_of;`

Header
  `#include <boost/align/alignment_of.hpp>`
Value

  The alignment requirement of the type `T` as an integral constant of type `std::size_t`. When `T` is a reference array type, the value shall be the alignment of the referenced type. When `T` is an array type, the value shall be the alignment of the element type.

Requires

  `T` shall be a complete object type, or an array thereof, or a reference to one of those types.

### Macros

#### BOOST_ALIGN_ASSUME_ALIGNED

`BOOST_ALIGN_ASSUME_ALIGNED(ptr, alignment)`

Header

  `#include <boost/align/assume_aligned.hpp>`

Requires
  - `alignment` shall be a power of two
  - `ptr` shall be mutable
Effects
  `ptr` may be modified in an implementation specific way to inform the compiler of its alignment.