| Home | Libraries | People | FAQ | More

## Reference

### align

The alignment function is used to obtain a pointer to the first address within the specified buffer that is a multiple of the specified alignment value. This function exists in the C++11 standard library but is provided in this library for those C++11 and C++03 library implementations which do not yet support it.

##### Header <boost/align/align.hpp>

    namespace boost {
      namespace alignment {
        void* align(std::size_t alignment, std::size_t size, void*& ptr,
          std::size_t& space);
      }
    }

##### Function align

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

> 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 fundamental alignment value or an extended alignment value, and 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_down

The directional alignment functions can be used with pointers or integral values to align down. This functionality is not yet provided by the C++ standard.

##### Header <boost/align/align_down.hpp>

    namespace boost {
      namespace alignment {
        constexpr std::size_t align_down(std::size_t value, std::size_t
          alignment) noexcept;

        void* align_down(void* ptr, std::size_t alignment) noexcept;
      }
    }

##### Function align_down

    void* align_down(void* ptr, std::size_t alignment) noexcept;

> Requires:

> - `ptr` shall point to contiguous storage with sufficient space for alignment
> - `alignment` shall be a power of two

> Returns: A pointer value at or before `ptr` that is at least `alignment` bytes aligned.

### align_up

The directional alignment functions can be used with pointers or integral values to align up. This functionality is not yet provided by the C++ standard.

##### Header <boost/align/align_up.hpp>

    namespace boost {
      namespace alignment {
        constexpr std::size_t align_up(std::size_t value, std::size_t
          alignment) noexcept;

        void* align_up(void* ptr, std::size_t alignment) noexcept;
      }
    }

##### Function align_up

    void* align_up(void* ptr, std::size_t alignment) noexcept;

> Requires:

> - `ptr` shall point to contiguous storage with sufficient space for alignment
> - `alignment` shall be a power of two

> Returns: A pointer value at or after `ptr` that is at least `alignment` bytes aligned.

### aligned_alloc and aligned_free

The aligned allocation function is a replacement for `::operator new(std::size_t, const std::no_throw_t&)` that allows requesting aligned memory. The deallocation function replaces the corresponding `::operator delete(void*)` function. This functionality is not yet provided by the C++ standard.

##### Header <boost/align/aligned_alloc.hpp>

    namespace boost {
      namespace alignment {
        void* aligned_alloc(std::size_t alignment, std::size_t size);

        void aligned_free(void* ptr);
      }
    }

##### Function aligned_alloc

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

> Effects: Allocates space for an object whose alignment is specified by `alignment`, whose size is specified by `size`, and whose value is indeterminate. The value of `alignment` shall be a power of two.

> Requires: `alignment` shall be a power of two.

> Returns: A null pointer or a pointer to the allocated space.

> Note: On certain platforms, the alignment may be rounded up to `alignof(void*)` and the space allocated may be slightly larger than `size` bytes, by an additional `sizeof(void*)` and `alignment - 1` bytes.

##### Function aligned_free

    void aligned_free(void* ptr);

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

### aligned_allocator

The aligned allocator is a replacement for the default allocator, `std::allocator`, that supports value types which are over-aligned. It also allows specifying a minimum alignment value used for all allocations, via the optional template parameter. An alignment aware allocator is not yet provided by the C++ standard.

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

##### Header <boost/align/aligned_allocator.hpp>

    namespace boost {
      namespace alignment {
        template<class T, std::size_t Alignment = 1>
        class aligned_allocator;

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

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

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

##### Class template aligned_allocator

    template<class T, std::size_t Alignment = 1>
    class aligned_allocator {
    public:
        typedef T value_type;
        typedef T* pointer;
        typedef const T* const_pointer;
        typedef void* void_pointer;
        typedef const void* const_void_pointer;
        typedef std::size_t size_type;
        typedef std::ptrdiff_t difference_type;
        typedef T& reference;
        typedef const T& const_reference;

        template<class U>
        struct rebind {
            typedef aligned_allocator<U, Alignment> other;
        };

        aligned_allocator() = default;

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

        pointer address(reference value) const noexcept;

        const_pointer address(const_reference value) const noexcept;

        pointer allocate(size_type size, const_void_pointer = 0);

        void deallocate(pointer ptr, size_type);

        size_type max_size() const noexcept;

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

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

    template<std::size_t Alignment>
    class aligned_allocator<void, Alignment> {
    public:
        typedef void value_type;
        typedef void* pointer;
        typedef const void* const_pointer;

        template<class U>
        struct rebind {
            typedef aligned_allocator<U, Alignment> other;
        };
    };

##### Members

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 address(reference value) const noexcept;

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

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

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

##### Globals

    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

The aligned allocator adaptor can turn any existing C++03 or C++11 allocator into one that supports value types that are over-aligned. It also allows specifying a minimum alignment value used for all allocations, via the optional template parameter. An alignment aware allocator adaptor is not yet provided by the C++ standard.

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

##### Header <boost/align/aligned_allocator_adaptor.hpp>

    namespace boost {
      namespace alignment {
        template<class Allocator, std::size_t Alignment = 1>
        class aligned_allocator_adaptor;

        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;

        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;
      }
    }

##### Class template aligned_allocator_adaptor

    template<class Allocator, std::size_t Alignment = 1>
    class aligned_allocator_adaptor
        : public Allocator {
        typedef std::allocator_traits<Allocator> Traits; // exposition

    public:
        typedef typename Traits::value_type value_type;
        typedef typename Traits::size_type size_type;
        typedef value_type* pointer;
        typedef const value_type* const_pointer;
        typedef void* void_pointer;
        typedef const void* const_void_pointer;
        typedef std::ptrdiff_t difference_type;

        template<class U>
        struct rebind {
            typedef aligned_allocator_adaptor<typename Traits::template
                rebind_alloc<U>, Alignment> other;
        };

        aligned_allocator_adaptor() = default;

        template<class A>
        explicit aligned_allocator_adaptor(A&& alloc) noexcept;

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

        Allocator& base() noexcept;

        const Allocator& base() const noexcept;

        pointer allocate(size_type size);

        pointer allocate(size_type size, const_void_pointer hint);

        void deallocate(pointer ptr, size_type size);
    };

##### Constructors

    aligned_allocator_adaptor() = default;

> Effects: Value-initializes the `Allocator` base class.

    template<class A>
    explicit 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()`.

##### Members

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

> 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 aligned allocator adaptor object, or else `nullptr`.

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

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

##### Globals

    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

The aligned deleter class is convenient utility for destroying and then deallocating the constructed objects that were allocated using aligned allocation function provided in this library. It serves as a replacement for the `std::default_delete` class for this case.

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

    namespace boost {
      namespace alignment {
        class aligned_delete;
      }
    }

##### Class aligned_delete

    class aligned_delete {
    public:
        template<class T>
        void operator()(T* ptr) const noexcept(noexcept(ptr->~T()));
    };

##### Members

    template<class T>
    void operator()(T* ptr) const noexcept(noexcept(ptr->~T()));

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

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

### alignment_of

The alignment type trait is used to query the alignment requirement of a type at compile time. It is provided by the C++11 standard library but is provided in this library for C++11 and C++03 implementations that do not provide this functionality.

##### Header <boost/align/alignment_of.hpp>

    namespace boost {
      namespace alignment {
        template<class T>
        struct alignment_of;

        template<class T>
        constexpr std::size_t alignment_of_v = alignment_of<T>::value;
      }
    }

##### Type trait alignment_of

    template<class T>
    struct alignment_of;

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

### assume_aligned

The alignment hint macro can be used to inform the compiler of the alignment of a memory block, to enable vectorizing or other compiler specific alignment related optimizations.

##### Header <boost/align/assume_aligned.hpp>

    BOOST_ALIGN_ASSUME_ALIGNED(ptr, alignment)

##### Macro BOOST_ALIGN_ASSUME_ALIGNED

    BOOST_ALIGN_ASSUME_ALIGNED(ptr, alignment)

> Requires:

> - `alignment` shall be a power of two
> - `ptr` shall be mutable

> Effect: `ptr` may be modified in an implementation specific way to inform the compiler of its alignment.

### is_aligned

The alignment validation function indicates whether or not an address is a multiple of the specified alignment value. It is generally useful in assertions to verify memory is correctly aligned. This functionality is not yet provided by the C++ standard.

##### Header <boost/align/is_aligned.hpp>

    namespace boost {
      namespace alignment {
        constexpr bool is_aligned(std::size_t value, std::size_t
          alignment) noexcept;

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

##### Function is_aligned

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

> Requires: `alignment` shall be a power of two.

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