| 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

`template<class T> constexpr T align_up(T value, std::size_t alignment) noexcept;`

  Header

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

  Constraints

    `T` is not a pointer type

  Requires

    `alignment` shall be a power of two

  Returns

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

#### align_down

`template<class T> constexpr T align_down(T value, std::size_t alignment) noexcept;`

  Header

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

  Constraints

    `T` is not a pointer type

  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 volatile void* ptr, std::size_t alignment) noexcept;`

  Header

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

  Requires

    `alignment` shall be a power of two.

  Returns

    `true` if `ptr` is aligned on the boundary specified by `alignment`, otherwise `false`.

`template<class T> constexpr bool is_aligned(T value, std::size_t alignment) noexcept;`

  Header

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

  Constraints

    `T` is not a pointer type

  Requires

    `alignment` shall be a power of two.

  Returns

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

### Classes

#### aligned_allocator

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

  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::add_lvalue_reference_t<T> reference;`
7. `typedef std::add_lvalue_reference_t<const T> const_reference;`
8. `typedef std::size_t size_type;`
9. `typedef std::ptrdiff_t difference_type;`
10. `typedef std::true_type propagate_on_container_move_assignment;`
11. `typedef std::true_type is_always_equal;`
12. `template<class U> struct rebind { typedef aligned_allocator<U, Alignment> other; };`

###### Constructors

`aligned_allocator() = default;`

  Effects

    Constructs the allocator.

`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.

`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.

`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*)`.

`size_type max_size() const noexcept;`

  Returns

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

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

  Effects

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

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

  Effects

    `ptr->~U()`.

###### Global operators

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

  Returns

    `true`

`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

`aligned_allocator_adaptor() = default;`

  Effects

    Value-initializes the `Allocator` base class.

`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)`.

`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

`Allocator& base() noexcept;`

  Returns

    `static_cast<Allocator&>(*this)`

`const Allocator& base() const noexcept;`

  Returns

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

`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 rebound copy of `base()` where its `value_type` is implementation defined.

  Throws

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

`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 rebound 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.

`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

`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()`

`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

`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.