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

NAME
     std::list - std::list

Synopsis
	Defined in header <list>
	template<

	    class T,							   (1)
	    class Allocator = std::allocator<T>

	> class list;
	namespace pmr {

	    template<  class  T >					     (2)
     (since C++17)
	    using list = std::list<T, std::pmr::polymorphic_allocator<T>>;

	}

	std::list is a container that supports constant time insertion	and  re-
     moval of
	elements  from anywhere in the container. Fast random access is not sup-
     ported. It is
	usually implemented as	a  doubly-linked  list.  Compared  to  std::for-
     ward_list this
	container  provides  bidirectional iteration capability while being less
     space
	efficient.

	Adding, removing and moving the elements within the list or across  sev-
     eral lists
	does  not invalidate the iterators or references. An iterator is invali-
     dated only
	when the corresponding element is deleted.

	std::list meets the requirements of Container, AllocatorAwareContainer,
	SequenceContainer and ReversibleContainer.

Template parameters
		    The type of the elements.

		    T must meet the requirements of  CopyConstructible.  T  must
     meet the (until
		    requirements   of	CopyAssignable	 if  list::operator=  or
     list::assign  C++11)
		    is instantiated with T.
		    The requirements that are imposed on the elements depend  on
     the    (since
		    actual  operations performed on the container. Generally, it
     is     C++11)
		    required that element type is a complete type and meets  the
     (until
		    requirements  of  Erasable, but many member functions impose
     C++17)
		    stricter requirements.
		    The requirements that are imposed on the elements depend  on
     the
		    actual  operations performed on the container. Generally, it
     is
	T	  -  required  that  element  type  meets  the	requirements  of
     Erasable, but
		    many  member  functions  impose  stricter requirements. This
     container
		    (but not its members) can be instantiated with an incomplete
		    element type if the allocator satisfies the  allocator  com-
     pleteness (since
		    requirements.
     C++17)

			      Feature-test    macro		  Value      Std
     Feature
									    Min-
     imal
		    __cpp_lib_incomplete_container_elements 201505L (C++17)  in-
     complete
									    type
									    sup-
     port

		    An allocator that is used to acquire/release memory and to
		    construct/destroy the elements in that memory. The type must
     meet the
		    requirements of Allocator.
	Allocator - The behavior is undefined
		    (until C++20)
		    The program is ill-formed
		    (since C++20) if Allocator::value_type is not the same as T.

Member types
	Member type	       Definition
	value_type	       T
	allocator_type	       Allocator
	size_type	       Unsigned integer type (usually std::size_t)
	difference_type        Signed integer type (usually std::ptrdiff_t)
	reference	       value_type&
	const_reference        const value_type&
			       Allocator::pointer			  (until
     C++11)
	pointer 	       std::allocator_traits<Allocator>::pointer  (since
     C++11)

			       Allocator::const_pointer
     (until C++11)
	const_pointer		 std::allocator_traits<Allocator>::const_pointer
     (since C++11)

	iterator	       LegacyBidirectionalIterator to value_type
	const_iterator	       LegacyBidirectionalIterator to const value_type
	reverse_iterator       std::reverse_iterator<iterator>
	const_reverse_iterator std::reverse_iterator<const_iterator>

Member functions
	constructor   constructs the list
		      (public member function)
	destructor    destructs the list
		      (public member function)
	operator=     assigns values to the container
		      (public member function)
	assign	      assigns values to the container
		      (public member function)
	assign_range  assigns a range of values to the container
	(C++23)       (public member function)
	get_allocator returns the associated allocator
		      (public member function)

Element access
	front	      access the first element
		      (public member function)
	back	      access the last element
		      (public member function)

Iterators
	begin	      returns an iterator to the beginning
	cbegin	      (public member function)
	(C++11)
	end	      returns an iterator to the end
	cend	      (public member function)
	(C++11)
	rbegin	      returns a reverse iterator to the beginning
	crbegin       (public member function)
	(C++11)
	rend	      returns a reverse iterator to the end
	crend	      (public member function)
	(C++11)

Capacity
	empty	      checks whether the container is empty
		      (public member function)
	size	      returns the number of elements
		      (public member function)
	max_size      returns the maximum possible number of elements
		      (public member function)

Modifiers
	clear	      clears the contents
		      (public member function)
	insert	      inserts elements
		      (public member function)
	insert_range  inserts a range of elements
	(C++23)       (public member function)
	emplace       constructs element in-place
	(C++11)       (public member function)
	erase	      erases elements
		      (public member function)
	push_back     adds an element to the end
		      (public member function)
	emplace_back  constructs an element in-place at the end
	(C++11)       (public member function)
	append_range  adds a range of elements to the end
	(C++23)       (public member function)
	pop_back      removes the last element
		      (public member function)
	push_front    inserts an element to the beginning
		      (public member function)
	emplace_front constructs an element in-place at the beginning
	(C++11)       (public member function)
	prepend_range adds a range of elements to the beginning
	(C++23)       (public member function)
	pop_front     removes the first element
		      (public member function)
	resize	      changes the number of elements stored
		      (public member function)
	swap	      swaps the contents
		      (public member function)

Operations
	merge	      merges two sorted lists
		      (public member function)
	splice	      moves elements from another list
		      (public member function)
	remove	      removes elements satisfying specific criteria
	remove_if     (public member function)
	reverse       reverses the order of the elements
		      (public member function)
	unique	      removes consecutive duplicate elements
		      (public member function)
	sort	      sorts the elements
		      (public member function)

Non-member functions
	operator==
	operator!=
	operator<
	operator<=
	operator>
	operator>=	     lexicographically compares the values of two lists
	operator<=>	     (function template)
	(removed in C++20)
	(removed in C++20)
	(removed in C++20)
	(removed in C++20)
	(removed in C++20)
	(C++20)
	std::swap(std::list) specializes the std::swap algorithm
			     (function template)
	erase(std::list)     erases all elements satisfying specific criteria
	erase_if(std::list)  (function template)
	(C++20)

	  Deduction guides (since C++17)

Notes
	    Feature-test macro	     Value    Std		    Feature
	__cpp_lib_containers_ranges 202202L (C++23) Ranges construction and  in-
     sertion for
						    containers

Example
     // Run this code

      #include <algorithm>
      #include <iostream>
      #include <list>

      int main()
      {
	  // Create a list containing integers
	  std::list<int> l = {7, 5, 16, 8};

	  // Add an integer to the front of the list
	  l.push_front(25);
	  // Add an integer to the back of the list
	  l.push_back(13);

	  // Insert an integer before 16 by searching
	  auto it = std::find(l.begin(), l.end(), 16);
	  if (it != l.end())
	      l.insert(it, 42);

	  // Print out the list
	  std::cout << "l = { ";
	  for (int n : l)
	      std::cout << n << ", ";
	  std::cout << "};\n";
      }

Output:
      l = { 25, 7, 5, 42, 16, 8, 13, };

	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
			   T was not required to be
	LWG 230 C++98	   CopyConstructible			T  is  also  re-
     quired to
			   (an	element  of  type  T  might  not be  be CopyCon-
     structible
			   able to be constructed)
	LWG 276 C++98	   T was always required to be	       only required  if
     operator= or
			   CopyAssignable		       assign is instan-
     tiated with T

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