Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/container/flat set"

From cppreference.com
< cpp‎ | container
m
m (→‎Member objects: =)
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{cpp/title|flat_set}}
 
{{cpp/title|flat_set}}
 
{{cpp/container/flat_set/navbar}}
 
{{cpp/container/flat_set/navbar}}
 +
{{ddcl|header=flat_set|since=c++23|1=
 +
template<
 +
    class Key,
 +
    class Compare = std::less<Key>,
 +
    class KeyContainer = std::vector<Key>
 +
> class flat_set;
 +
}}
  
−
{{todo}}
+
The flat set is a [[cpp/container#Container adaptors|container adaptor]] that gives the functionality of an associative container that stores a sorted set of unique objects of type {{tt|Key}}. Sorting is done using the key comparison function {{tt|Compare}}.
 +
 
 +
The class template {{tt|flat_set}} acts as a wrapper to the underlying sorted container passed as object of type {{tt|KeyContainer}}.
 +
 
 +
Everywhere the standard library uses the {{named req|Compare}} requirements, uniqueness is determined by using the equivalence relation. Informally, two objects {{c|a}} and {{c|b}} are considered equivalent if neither compares less than the other: {{c|!comp(a, b) && !comp(b, a)}}.
 +
 
 +
{{tt|std::flat_set}} meets the requirements of {{named req|Container}}, {{named req|ReversibleContainer}}, {{lsd|cpp/named_req/Container#Optional container requirements}}, and all requirements of {{named req|AssociativeContainer}} (including logarithmic search complexity), except that:
 +
* requirements related to nodes are not applicable,
 +
* iterator invalidation requirements differ, <!--TODO: describe iterator/pointer invalidation properties, maybe per each function -->
 +
* the complexity of insertion and erasure operations is linear.<!--TODO: add the list of member functions (with usual semantics) that must be present in adapted container-->
 +
 
 +
A flat set supports most {{named req|AssociativeContainer}}'s operations that use unique keys.
 +
 
 +
===Iterator invalidation===
 +
{{todo}} <!-- TODO: see e.g. [[cpp/container/unordered_set#Iterator invalidation]] as a basis -->
 +
 
 +
===Template parameters===
 +
{{par begin}}
 +
{{par|Key|The type of the stored elements. The program is ill-formed if {{tt|Key}} is not the same type as {{tt|KeyContainer::value_type}}.}}
 +
{{par|Compare|A {{named req|Compare}} type providing a strict weak ordering.
 +
{{par|KeyContainer|The type of the underlying {{named req|SequenceContainer}} to store the elements. The iterators of such container should satisfy {{named req|RandomAccessIterator}} or model {{lconcept|random_access_iterator}}.
 +
 
 +
The standard containers {{lc|std::vector}} and {{lc|std::deque}} satisfy these requirements.}}}}{{par end}}
 +
<!---->
 +
===Member types===
 +
{{dsc begin}}
 +
{{dsc hitem|Type|Definition}}
 +
{{dsc inc|cpp/container/dsc container_type|flat_set}}
 +
{{dsc inc|cpp/container/dsc key_type|flat_set}}
 +
{{dsc inc|cpp/container/dsc value_type|flat_set}}
 +
{{dsc inc|cpp/container/dsc key_compare|flat_set}}
 +
{{dsc inc|cpp/container/dsc value_compare2|flat_set}}
 +
{{dsc inc|cpp/container/dsc reference|flat_set}}
 +
{{dsc inc|cpp/container/dsc const_reference|flat_set}}
 +
{{dsc inc|cpp/container/dsc size_type|flat_set}}
 +
{{dsc inc|cpp/container/dsc difference_type|flat_set}}
 +
{{dsc inc|cpp/container/dsc iterator|flat_set}}
 +
{{dsc inc|cpp/container/dsc const_iterator|flat_set}}
 +
{{dsc inc|cpp/container/dsc reverse_iterator|flat_set}}
 +
{{dsc inc|cpp/container/dsc const_reverse_iterator|flat_set}}
 +
{{dsc end}}
 +
 
 +
===Member objects===
 +
{{dsc begin}}
 +
{{dsc hitem|Member|Description}}
 +
{{dsc expos mem obj|private=yes|spec={{tt|container_type}}|id=c|c|the adapted container}}
 +
{{dsc expos mem obj|private=yes|spec={{tt|key_compare}}|id=key_compare|compare|the comparison function object}}
 +
{{dsc end}}
 +
 
 +
===Member functions===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/container/dsc constructor|flat_set}}
 +
{{dsc mem dtor|nolink=true|notes={{mark implicit}}|destroys every element of the container adaptor}}
 +
{{dsc inc|cpp/container/dsc operator{{=}}|flat_set}}
 +
 
 +
{{dsc h2|Iterators}}
 +
{{dsc inc|cpp/container/dsc begin|flat_set}}
 +
{{dsc inc|cpp/container/dsc end|flat_set}}
 +
{{dsc inc|cpp/container/dsc rbegin|flat_set}}
 +
{{dsc inc|cpp/container/dsc rend|flat_set}}
 +
 
 +
{{dsc h2|Capacity}}
 +
{{dsc inc|cpp/container/dsc empty|flat_set}}
 +
{{dsc inc|cpp/container/dsc size|flat_set}}
 +
{{dsc inc|cpp/container/dsc max_size|flat_set}}
 +
 
 +
{{dsc h2|Modifiers}}
 +
{{dsc inc|cpp/container/dsc emplace|flat_set}}
 +
{{dsc inc|cpp/container/dsc emplace_hint|flat_set}}
 +
{{dsc inc|cpp/container/dsc insert|flat_set}}
 +
{{dsc inc|cpp/container/dsc insert_range|flat_set}}
 +
{{dsc inc|cpp/container/dsc extract|flat_set}}
 +
{{dsc inc|cpp/container/dsc replace|flat_set}}
 +
{{dsc inc|cpp/container/dsc erase|flat_set}}
 +
{{dsc inc|cpp/container/dsc swap|flat_set}}
 +
{{dsc inc|cpp/container/dsc clear|flat_set}}
 +
 
 +
{{dsc h2|Lookup}}
 +
{{dsc inc|cpp/container/dsc find|flat_set}}
 +
{{dsc inc|cpp/container/dsc count|flat_set}}
 +
{{dsc inc|cpp/container/dsc contains|flat_set}}
 +
{{dsc inc|cpp/container/dsc lower_bound|flat_set}}
 +
{{dsc inc|cpp/container/dsc upper_bound|flat_set}}
 +
{{dsc inc|cpp/container/dsc equal_range|flat_set}}
 +
 
 +
{{dsc h2|Observers}}
 +
{{dsc inc|cpp/container/dsc key_comp|flat_set}}
 +
{{dsc inc|cpp/container/dsc value_comp|flat_set}}
 +
{{dsc end}}
 +
 
 +
===Non-member functions===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/container/dsc operator_cmp|flat_set}}
 +
{{dsc inc|cpp/container/dsc swap2|flat_set}}
 +
{{dsc inc|cpp/container/dsc erase_if|flat_set}}
 +
{{dsc end}}
 +
 
 +
===Helper classes===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/container/dsc uses_allocator|flat_set}}
 +
{{dsc end}}
 +
 
 +
===Tags===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/container/dsc sorted_unique}}
 +
{{dsc end}}
 +
 
 +
==={{rl|deduction guides|Deduction guides}}===
 +
 
 +
===Notes===
 +
{{cpp/container/assoc_note}}<!-- TODO: is this relevant to flat_set? -->
 +
 
 +
Some advantages of flat set over other standard {{lsd|cpp/container#Container adaptors}} are: <!-- TODO: maybe this lyrics is unnecessary: -->
 +
* Potentially faster lookup (even though search operations have logarithmic complexity).
 +
* Much faster iteration: {{lt|cpp/iterator/random access iterator}}s instead of {{lt|cpp/iterator/bidirectional iterator}}s.
 +
* Less memory consumption for small objects (and for big objects if {{c|KeyContainer::shrink_to_fit()}} is available).
 +
* Better cache performance (depending on {{tt|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-movable types.
 +
 
 +
{{ftm begin}}
 +
{{ftm|__cpp_lib_flat_set|value=202207L|std=C++23|{{tt|std::flat_set}} and {{lc|std::flat_multiset}}}}
 +
{{ftm end}}
 +
 
 +
===Example===
 +
{{example}}
 +
 
 +
===See also===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/container/dsc flat_multiset}}
 +
{{dsc inc|cpp/container/dsc set}}
 +
{{dsc inc|cpp/container/dsc unordered_set}}
 +
{{dsc end}}
 +
 
 +
{{langlinks|cs|de|es|fr|it|ja|pl|pt|ru|zh}}
 +
 
 +
<!--TODO: N4950::24.6.11 says:
 +
TODO: add this to the "Exceptions" sections of appropriate member functions:
 +
6. If any member function in 24.6.11.2 exits via an exception, the invariant is restored.
 +
[Note 2 : This can result in the flat_set’s being emptied. — end note].
 +
-->
 +
 
 +
<!--TODO: N4950::24.6.11 says:
 +
TODO: add to constructors:
 +
9. The effect of calling a constructor or member function that takes a sorted_unique_t argument with a range that is not sorted with respect to key_comp(), or that contains equal elements, is undefined.
 +
-->
 +
 
 +
<!-- TODO: also complete [[cpp/container#Iterator invalidation]] table for flat_* adaptors -->

Latest revision as of 14:53, 1 November 2024

 
C++
 
Containers library
 
std::flat_set
Member types
Member functions
Helper classes
Tags
Deduction guides
 
Defined in header <flat_set>
template<

    class Key,
    class Compare = std::less<Key>,
    class KeyContainer = std::vector<Key>

> class flat_set;
 (since C++23)

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. Sorting 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, uniqueness 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.

Contents

[edit] Iterator invalidation

This section is incomplete

[edit] 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.
KeyContainer - The type of the underlying SequenceContainer to store the elements. The iterators of such container should satisfy LegacyRandomAccessIterator or model random_access_iterator.

The standard containers std::vector and std::deque satisfy these requirements.

[edit] Member types

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

[edit] Member objects

Member Description
container_type c (private) the adapted container
(exposition-only member object*)
key_compare compare (private) the comparison function object
(exposition-only member object*)

[edit] Member functions

 constructs the flat_set
(public member function) [edit]
(destructor)
(implicitly declared)
 destroys every element of the container adaptor
(public member function)
assigns values to the container adaptor
(public member function) [edit]
Iterators
returns an iterator to the beginning
(public member function) [edit]
returns an iterator to the end
(public member function) [edit]
returns a reverse iterator to the beginning
(public member function) [edit]
returns a reverse iterator to the end
(public member function) [edit]
Capacity
checks whether the container adaptor is empty
(public member function) [edit]
returns the number of elements
(public member function) [edit]
returns the maximum possible number of elements
(public member function) [edit]
Modifiers
constructs element in-place
(public member function) [edit]
constructs elements in-place using a hint
(public member function) [edit]
inserts elements
(public member function) [edit]
inserts a range of elements
(public member function) [edit]
extracts the underlying container
(public member function) [edit]
replaces the underlying container
(public member function) [edit]
erases elements
(public member function) [edit]
swaps the contents
(public member function) [edit]
clears the contents
(public member function) [edit]
Lookup
finds element with specific key
(public member function) [edit]
returns the number of elements matching specific key
(public member function) [edit]
checks if the container contains element with specific key
(public member function) [edit]
returns an iterator to the first element not less than the given key
(public member function) [edit]
returns an iterator to the first element greater than the given key
(public member function) [edit]
returns range of elements matching a specific key
(public member function) [edit]
Observers
returns the function that compares keys
(public member function) [edit]
returns the function that compares keys in objects of type value_type
(public member function) [edit]

[edit] Non-member functions

(C++23)
 lexicographically compares the values of two flat_sets
(function template) [edit]
(C++23)
 specializes the std::swap algorithm
(function template) [edit]
(C++23)
 erases all elements satisfying specific criteria
(function template) [edit]

[edit] Helper classes

(C++23)
 specializes the std::uses_allocator type trait
(class template specialization) [edit]

[edit] Tags

(C++23)
 indicates that elements of a range are sorted and unique
(tag)[edit]

[edit] Deduction guides

[edit] 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 parameter 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 logarithmic complexity).
  • Much faster iteration: random access iterators instead of bidirectional 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-movable types.
Feature-test macro Value Std Feature
__cpp_lib_flat_set 202207L (C++23) std::flat_set and std::flat_multiset

[edit] Example

This section is incomplete
Reason: no example

[edit] See also

(C++23)
 adapts a container to provide a collection of keys, sorted by keys
(class template) [edit]
collection of unique keys, sorted by keys
(class template) [edit]
(C++11)
 collection of unique keys, hashed by keys
(class template) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/container/flat_set&oldid=177443"