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

NAME
     std::list::list - std::list::list

Synopsis
	list(); 					 (1)
	explicit list( const Allocator& alloc );	 (2)
	explicit list( size_type count,

		       const T& value = T(),			 (until C++11)

		       const Allocator& alloc =
	Allocator() );
	list( size_type count,

	      const T& value,					 (since C++11)

	      const Allocator& alloc = Allocator() );
	explicit	   list(	   size_type	       count	      );
     (since C++11)
									       (un-
     til C++14)
	explicit list( size_type count,
		       const		Allocator&	      alloc	       =
     (since C++14)
	Allocator() );
	template< class InputIt >			 (3)

	list( InputIt first, InputIt last,			 (5)

	      const Allocator& alloc = Allocator() );
	list( const list& other );			     (4) (6)
	list(	const	list&	other,	 const	 Allocator&  alloc	     (7)
     (since C++11)
	);
	list(	 list&&    other    );					     (8)
     (since C++11)
	list(	list&&	 other,   const   Allocator&   alloc  );	     (9)
     (since C++11)
	list(	 std::initializer_list<T>     init,			    (10)
     (since C++11)
	      const Allocator& alloc = Allocator() );
	template< container-compatible-range<T> R >

	list(	 std::from_range_t,    R&&    rg,			    (11)
     (since C++23)

	      const Allocator& alloc = Allocator() );

	Constructs a new container from a variety of  data  sources,  optionally
     using a user
	supplied allocator alloc.

	1)  Default  constructor.  Constructs an empty container with a default-
     constructed
	allocator.
	2) Constructs an empty container with the given allocator alloc.
	3) Constructs the container with count copies  of  elements  with  value
     value.
	4)  Constructs the container with count default-inserted instances of T.
     No copies
	are made.
	5) Constructs the container with  the  contents  of  the  range  [first,
     last).

	This constructor has the same effect as
	list(static_cast<size_type>(first),   static_cast<value_type>(last),  a)
     (until C++11)
	if InputIt is an integral type.
	This overload participates in overload resolution only if InputIt
	satisfies LegacyInputIterator, to  avoid  ambiguity  with  the	overload
     (since C++11)
	(3).

	6)  Copy constructor. Constructs the container with the copy of the con-
     tents of
	other.

	The	allocator     is     obtained	  as	 if	 by	 calling
     (since
	std::allocator_traits<allocator_type>::select_on_container_copy_con-
     struction( C++11)
	    other.get_allocator()).

	7)  Constructs the container with the copy of the contents of other, us-
     ing alloc as
	the allocator.

	During class template argument deduction, only the first argument
	contributes to the  deduction  of  the	container's  Allocator	template
     (since C++23)
	parameter.

	8) Move constructor. Constructs the container with the contents of other
     using move
	semantics. Allocator is obtained by move-construction from the allocator
     belonging
	to other.
	9) Allocator-extended move constructor. Using alloc as the allocator for
     the new
	container, moving the contents from other; if alloc != other.get_alloca-
     tor(), this
	results in an element-wise move.

	During class template argument deduction, only the first argument
	contributes  to  the  deduction  of  the  container's Allocator template
     (since C++23)
	parameter.

	10) Constructs the container with the contents of the  initializer  list
     init.
	11) Constructs the container with the contents of the range rg.

Parameters
	alloc	     -	allocator to use for all memory allocations of this con-
     tainer
	count	    - the size of the container
	value	    - the value to initialize elements of the container with
	first, last - the range [first, last) to copy the elements from
	other	    - another container to be used as source to  initialize  the
     elements of
		      the container with
	init	     -	initializer  list to initialize the elements of the con-
     tainer with
	rg	    - a container compatible  range,  that  is,  an  input_range
     whose elements
		      are convertible to T

Complexity
	1,2) Constant.
	3,4) Linear in count.
	5) Linear in distance between first and last.
	6,7) Linear in size of other.
	8) Constant.
	9) Linear if alloc != other.get_allocator(), otherwise constant.
	10) Linear in size of init.
	11) Linear in ranges::distance(rg).

Exceptions
	Calls to Allocator::allocate may throw.

Notes
	After  container move construction (overload (8)), references, pointers,
     and
	iterators (other than the end iterator) to other remain valid, but refer
     to elements
	that are now in *this. The current standard makes this guarantee via the
     blanket
	statement in [container.reqmts]/67, and a more direct guarantee is under
	consideration via LWG issue 2321.

	    Feature-test macro	     Value    Std		    Feature
	__cpp_lib_containers_ranges 202202L  (C++23)  Ranges-aware  construction
     and insertion;
						    overload (11)

Example
     // Run this code

      #include <iostream>
      #include <string>
      #include <list>

      template<typename T>
      std::ostream& operator<<(std::ostream& s, const std::list<T>& v)
      {
	  s.put('{');
	  for (char comma[]{'\0', ' ', '\0'}; const auto& e : v)
	      s << comma << e, comma[0] = ',';
	  return s << "}\n";
      }

      int main()
      {
	  // C++11 initializer list syntax:
	  std::list<std::string>    words1{"the",   "frogurt",	 "is",	 "also",
     "cursed"};
	  std::cout << "1: " << words1;

	  // words2 == words1
	  std::list<std::string> words2(words1.begin(), words1.end());
	  std::cout << "2: " << words2;

	  // words3 == words1
	  std::list<std::string> words3(words1);
	  std::cout << "3: " << words3;

	  // words4 is {"Mo", "Mo", "Mo", "Mo", "Mo"}
	  std::list<std::string> words4(5, "Mo");
	  std::cout << "4: " << words4;

	  auto const rg = {"cat", "cow", "crow"};
      #ifdef __cpp_lib_containers_ranges
	  std::list<std::string> words5(std::from_range, rg); // overload (11)
      #else
	  std::list<std::string> words5(rg.begin(), rg.end()); // overload (5)
      #endif
	  std::cout << "5: " << words5;
      }

Output:
      1: {the, frogurt, is, also, cursed}
      2: {the, frogurt, is, also, cursed}
      3: {the, frogurt, is, also, cursed}
      4: {Mo, Mo, Mo, Mo, Mo}
      5: {cat, cow, crow}

	Defect reports

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

	   DR	  Applied  to	      Behavior as published		 Correct
     behavior
	LWG 868  C++98	    for overload (4),  the  elements  in  the  they  are
     value-initialized
			    container were default constructed
	LWG  2193  C++11      the default constructor is explicit   made non-ex-
     plicit

See also
	assign	  assigns values to the container
		  (public member function)
	operator= assigns values to the container
		  (public member function)

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