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

NAME
     std::allocator::allocate - std::allocator::allocate

Synopsis
	pointer allocate( size_type n, const void*	    (until C++17)
	hint = 0 );
	T* allocate( std::size_t n, const void* 	    (since C++17)
	hint ); 					    (deprecated)
						    (1)     (removed in C++20)
	T*	      allocate( 	   std::size_t		  n	      );
     (since C++17)
							(2)
     (until C++20)
	[[nodiscard]]		  constexpr		T*	       allocate(
     (since C++20)
	std::size_t n );

	Allocates  n * sizeof(T) bytes of uninitialized storage by calling ::op-
     erator
	new(std::size_t)
	or ::operator new(std::size_t, std::align_val_t)
	(since C++17), but it is unspecified  when  and  how  this  function  is
     called. The
	pointer  hint  may be used to provide locality of reference: the alloca-
     tor, if
	supported by the implementation, will attempt to allocate the new memory
     block as
	close as possible to hint.

	Then, this function creates an array of type T[n]  in  the  storage  and
     starts its
	lifetime, but does not start lifetime of any of its elements.

	Use of this function is ill-formed if T is an incomplete type.

	In order to use this function in a constant expression, the allocated
	storage   must	 be  deallocated  within  the  evaluation  of  the  same
     (since C++20)
	expression.

Parameters
	n    - the number of objects to allocate storage for
	hint - pointer to a nearby memory location

Return value
	Pointer to the first element of an array of n objects of  type	T  whose
     elements have
	not been constructed yet.

Exceptions
	Throws			  std::bad_array_new_length		      if
     (since C++11)
	std::numeric_limits<std::size_t>::max() / sizeof(T) < n.

	Throws std::bad_alloc if allocation fails.

Notes
	The "unspecified when and how" wording makes it possible to  combine  or
     optimize away
	heap  allocations  made  by the standard library containers, even though
     such
	optimizations are disallowed for direct calls to ::operator new. For ex-
     ample, this
	is implemented by libc++ ([1] and [2]).

	After calling allocate() and before construction  of  elements,  pointer
     arithmetic of
	T* is well-defined within the allocated array, but the behavior is unde-
     fined if
	elements are accessed.

	Defect reports

	The  following	behavior-changing  defect  reports were applied retroac-
     tively to
	previously published C++ standards.

	   DR	 Applied to	 Behavior as published		    Correct  be-
     havior
			    hint was required to be either
			    0 or a
	LWG 578  C++98	    pointer previously returned     not required
			    from allocate()
			    and not yet passed to
			    deallocate()
	LWG  3190 C++11      allocate() might allocate	     throws std::bad_ar-
     ray_new_length
			    storage of wrong size	    instead

See also
	allocate allocates uninitialized storage using the allocator
	[static] (public static member function of std::allocator_traits<Alloc>)

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