home | help 
std::aligned_storage(3)        C++ Standard Libary	 std::aligned_storage(3)

NAME
     std::aligned_storage - std::aligned_storage

Synopsis
	Defined in header <type_traits>
	template<  std::size_t	Len,  std::size_t Align = /*		  (since
     C++11)
	default-alignment */  > 					 (depre-
     cated in C++23)
	struct aligned_storage;

	Provides the nested type type, which satisfies TrivialType and Standard-
     LayoutType
	and  suitable for use as uninitialized storage for any object whose size
     is at most
	Len and whose alignment requirement is a divisor of Align.

	The default value of Align is the most stringent (the largest) alignment
     requirement
	for any object whose size is at most Len. If the default  value  is  not
     used, Align
	must  be the value of alignof(T) for some type T, or the behavior is un-
     defined.

	The behavior is undefined if Len == 0.

	It is implementation-defined whether  any  extended  alignment	is  sup-
     ported.

	If the program adds specializations for std::aligned_storage, the behav-
     ior is
	undefined.

Member types
	Name Definition
	type a trivial and standard-layout type of at least size Len with align-
     ment
	     requirement Align

Helper types
	template< std::size_t Len, std::size_t Align = /*
	default-alignment  */  >					  (since
     C++14)
	using aligned_storage_t = typename  aligned_storage<Len,	 (depre-
     cated in C++23)
	Align>::type;

Notes
	The  type  defined by std::aligned_storage<>::type can be used to create
     uninitialized
	memory blocks suitable to hold the objects  of	given  type,  optionally
     aligned
	stricter  than	their  natural	alignment  requirement, for example on a
     cache or page
	boundary.

	As with any other uninitialized storage, the objects are  created  using
     placement new
	and destroyed with explicit destructor calls.

Possible implementation
	Except	for default argument, aligned_storage is expressible in terms of
     alignas:

	template<std::size_t Len, std::size_t Align = /* default  alignment  not
     implemented */>
	struct aligned_storage
	{
	    struct type
	    {
		alignas(Align) unsigned char data[Len];
	    };
	};

Example
	A primitive static vector class, demonstrating creation, access, and de-
     struction of
	objects in aligned storage.

     // Run this code

      #include <cstddef>
      #include <iostream>
      #include <new>
      #include <string>
      #include <type_traits>

      template<class T, std::size_t N>
      class static_vector
      {
	  // Properly aligned uninitialized storage for N T's
	  std::aligned_storage_t<sizeof(T), alignof(T)> data[N];
	  std::size_t m_size = 0;

      public:
	  // Create an object in aligned storage
	  template<typename ...Args> void emplace_back(Args&&... args)
	  {
	      if (m_size >= N) // Possible error handling
		  throw std::bad_alloc{};

	      //  Construct value in memory of aligned storage using inplace op-
     erator new
	      ::new(&data[m_size]) T(std::forward<Args>(args)...);
	      ++m_size;
	  }

	  // Access an object in aligned storage
	  const T& operator[](std::size_t pos) const
	  {
	      // Note: std::launder is needed after the change of  object  model
     in P0137R1
	      return *std::launder(reinterpret_cast<const T*>(&data[pos]));
	  }

	  // Destroy objects from aligned storage
	  ~static_vector()
	  {
	      for (std::size_t pos = 0; pos < m_size; ++pos)
		  //  Note:  std::launder  is  needed after the change of object
     model in P0137R1
		  std::destroy_at(std::launder(reinter-
     pret_cast<T*>(&data[pos])));
	  }
      };

      int main()
      {
	  static_vector<std::string, 10> v1;
	  v1.emplace_back(5, '*');
	  v1.emplace_back(10, '*');
	  std::cout << v1[0] << '\n' << v1[1] << '\n';
      }

Output:
      *****
      **********

See also
	alignas specifier(C++11)     specifies that the storage for the variable
     should be
				     aligned by specific amount
	alignment_of		     obtains the type's alignment requirements
	(C++11) 		     (class template)
	aligned_alloc		     allocates aligned memory
	(C++17) 		     (function)
	aligned_union		     defines the type suitable for use as unini-
     tialized
	(C++11)(deprecated in C++23) storage for all given types
				     (class template)
	max_align_t		     trivial type with alignment requirement  as
     great as any
	(C++11) 		     other scalar type
				     (typedef)
	launder 		     pointer optimization barrier
	(C++17) 		     (function template)

http://cppreference.com 	   2024.06.10		 std::aligned_storage(3)
home | help