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

NAME
     std::flat_set - std::flat_set

Synopsis
	Defined in header <flat_set>
	template<

	    class Key,
	    class Compare = std::less<Key>,	   (since C++23)
	    class KeyContainer = std::vector<Key>

	> class flat_set;

	The  flat  set is a container adaptor that gives the functionality of an
     associative
	container that stores a sorted set of unique objects of type Key.  Sort-
     ing is done
	using the key comparison function Compare.

	The  class  template flat_set acts as a wrapper to the underlying sorted
     container
	passed as object of type KeyContainer.

	Everywhere the standard library uses the Compare  requirements,  unique-
     ness is
	determined  by using the equivalence relation. Informally, two objects a
     and b are
	considered equivalent if neither compares less than the other:	!comp(a,
     b) &&
	!comp(b, a).

	std::flat_set  meets the requirements of Container, ReversibleContainer,
     optional
	container requirements, and  all  requirements	of  AssociativeContainer
     (including
	logarithmic search complexity), except that:

	  * requirements related to nodes are not applicable,
	  * iterator invalidation requirements differ,
	  * the complexity of insertion and erasure operations is linear.

	A  flat  set  supports	most  AssociativeContainer's operations that use
     unique keys.

Template parameters
	Key	     - The type of the stored  elements.  The  program	is  ill-
     formed if Key is
		       not the same type as KeyContainer::value_type.
	Compare      - A Compare type providing a strict weak ordering.
		       The type of the underlying SequenceContainer to store the
     elements.
		       The iterators of such container should satisfy
	KeyContainer  - LegacyRandomAccessIterator or model random_access_itera-
     tor.

		       The standard containers std::vector and	std::deque  sat-
     isfy these
		       requirements.

Member types
	Member type	       Definition
	container_type	       KeyContainer
	key_type	       Key
	value_type	       Key
	key_compare	       Compare
	value_compare	       Compare
	reference	       value_type&
	const_reference        const value_type&
	size_type	       typename KeyContainer::size_type
	difference_type        typename KeyContainer::difference_type
	iterator	       implementation-defined LegacyRandomAccessIterator
     and
			       random_access_iterator to value_type
	const_iterator	       implementation-defined LegacyRandomAccessIterator
     and
			       random_access_iterator to const value_type
	reverse_iterator       std::reverse_iterator<iterator>
	const_reverse_iterator std::reverse_iterator<const_iterator>

Member objects
	Member name	  Definition
	c (private)	  the underlying container of container_type
			  (exposition-only member object*)
	compare (private) the comparison function object of type key_compare
			  (exposition-only member object*)

Member functions
	constructor	      constructs the flat_set
			      (public member function)
	destructor	      destroys every element of the container adaptor
	(implicitly declared) (public member function)
	operator=	      assigns values to the container adaptor
			      (public member function)

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

Capacity
	empty		      checks whether the container adaptor 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
	emplace 	      constructs element in-place
			      (public member function)
	emplace_hint	      constructs elements in-place using a hint
			      (public member function)
	insert		      inserts elements
			      (public member function)
	insert_range	      inserts a range of elements
			      (public member function)
	extract 	      extracts the underlying container
			      (public member function)
	replace 	      replaces the underlying container
			      (public member function)
	erase		      erases elements
			      (public member function)
	swap		      swaps the contents
			      (public member function)
	clear		      clears the contents
			      (public member function)

Lookup
	find		      finds element with specific key
			      (public member function)
	count		       returns	the number of elements matching specific
     key
			      (public member function)
	contains	      checks if the container contains element with spe-
     cific key
			      (public member function)
			      returns an iterator to the first element not  less
     than the
	lower_bound	      given key
			      (public member function)
			      returns  an  iterator to the first element greater
     than the
	upper_bound	      given key
			      (public member function)
	equal_range	      returns range of elements matching a specific key
			      (public member function)

Observers
	key_comp	      returns the function that compares keys
			      (public member function)
			      returns the function that compares keys in objects
     of type
	value_comp	      value_type
			      (public member function)

Non-member functions
	operator==		 lexicographically compares the  values  of  two
     flat_sets
	operator<=>		 (function template)
	(C++23)
	std::swap(std::flat_set) specializes the std::swap algorithm
	(C++23) 		 (function template)
	erase_if(std::flat_set)   erases all elements satisfying specific crite-
     ria
	(C++23) 		 (function template)

Helper classes
	std::uses_allocator<std::flat_set> specializes	the  std::uses_allocator
     type trait
	(C++23) 			   (class template specialization)

	Tags

	sorted_unique	indicates that elements of a range are sorted and unique
	sorted_unique_t (tag)
	(C++23)

	Deduction guides

Notes
	The  member types iterator and const_iterator may be aliases to the same
     type. This
	means defining a pair of function overloads using the two types as para-
     meter types
	may violate the One Definition Rule. Since iterator is convertible to
	const_iterator, a single function with	a  const_iterator  as  parameter
     type will work
	instead.

	Some advantages of flat set over other standard container adaptors are:

	  *  Potentially faster lookup (even though search operations have loga-
     rithmic
	    complexity).
	  * Much faster iteration: random access iterators instead  of	bidirec-
     tional
	    iterators.
	  * Less memory consumption for small objects (and for big objects if
	    KeyContainer::shrink_to_fit() is available).
	  * Better cache performance (depending on KeyContainer, keys are stored
     in a
	    contiguous block(s) of memory).

	Some disadvantages of flat set are:

	  *  Non-stable  iterators (iterators are invalidated when inserting and
     erasing
	    elements).
	  * Non-copyable and non-movable type values can not be stored.
	  * Weaker exception  safety  (copy/move  constructors	can  throw  when
     shifting values
	    in erasures and insertions).
	  *  Slower (i.e. linear) insertion and erasure, especially for non-mov-
     able types.

	Feature-test macro  Value    Std		 Feature
	__cpp_lib_flat_set 202207L (C++23) std::flat_set and std::flat_multiset

Example
	 This section is incomplete
	 Reason: no example

See also
	flat_multiset adapts a container to provide a collection of keys, sorted
     by keys
	(C++23)       (class template)
	set	      collection of unique keys, sorted by keys
		      (class template)
	unordered_set collection of unique keys, hashed by keys
	(C++11)       (class template)

Categories:
	  * Todo without reason
	  * Todo no example

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