====== MULTISET ======

===== Opis =====


Multiset - multizbior.

Multiset jest kontenerem asocjacyjnym, w którym przechowywane są elementy typu Key. Multiset jest również kontenerem, w którym możne występować dwa lub więcej elementów o takim samym kluczu.


===== Definicja =====

Multiset jest zdefiniowany w standardowym nagłówku set oraz w niestandardowym kompatybilnym wstecz nagłówku multiset.h


===== Parametry szablonowe =====

std::multiset<Key,Compare,Alloc>

==== Key ====

Jest typem jaki jest przechowywany w multizbiorze. Jest również zdefiniowana jako multiset::key_type  oraz multiset::value_type.

Key musi spełniać następujące wymagania:
  * posiadać konstruktor kopiujący
  * posiadać operator przypisania
  * udostępniać funkcje __void swap(Key,Key)__ która zamienia miejscami elementu podane jako argumenty


==== Compare ====

Jest typem za pomocą którego określa się kolejność przechowywanych elementów. Jest również zdefiniowana jako multiset::key_compare oraz multiset::value_compare. Domyślna wartość to: less<T> .

Compare musi spełniać następujące wymagania:
  * posiadać operator wywolania funkcyjnego __bool operator()(Key,Key)__ który zwraca true, gdy pierwszy argument jest mniejszy od drugiego, a w przeciwnym przypadku zwraca false


==== Alloc ====

Jest to alokator używany do zarządzania pamięcią. Domyślna wartość to alloc .


===== Typy =====

==== Iteratory ====

Zdefiniowane są następujące typy iteratorów:
  * multiset::iterator               - pozwala na sekwencyjny dostęp do elementów multizbioru
  * multiset::const_iterator         - pozwala na sekwencyjny dostęp do elementów multizbioru (bez możliwości zmiany ich)
  * multiset::reverse_iterotor       - pozwala na sekwencyjny dostęp do elementów multizbioru (od końca do początku)
  * multiset::const_reverse_iterator - pozwala na sekwencyjny dostęp do elementów multizbioru (od końca do początku, bez możliwości zmiany ich)

==== Referencje ====

Zdefiniowane są następujące typy referencji:
  * multiset::reference       - typ będący referencją do elementów multizbioru
  * multiset::const_reference - typ będący stała referencją do elementów multizbioru

==== Inne ====

Inne zdefiniowane typy to:
  * multiset::key_compare , multiset::value_compare - typ określający sposób porównywania elementów 
  * multiset::key_type ,multiset::value_type        - typ przechowywanych elementów
  * multiset::size_type                             - typ określający odległość pomiędzy elementami (nieujemna) 
  * multiset::difference_type                       - typ określający odległość pomiędzy elementami (może być ze znakiem)


===== Metody =====

==== Konstruktory ====

=== multiset() ===
Konstruktor domyślny, tworzący pusty multizbiór.

=== multiset(const key_compare& comp) ===
Tworzy pusty multizbiór, używający podanego obiektu do porównywania elementów.

=== template <class InputIterator> multiset(InputIterator f, InputIterator l) ===
Tworzy multizbiór, posiadający elementy z zadanego zakresu.

=== template <class InputIterator> multiset(InputIterator f, InputIterator l, const key_compare& comp) ===
Tworzy multizbiór, posiadający elementy z zadanego zakresu i używający podanego obiektu do porównywania elementów.

=== multiset(const multiset&) ===
Konstruktor kopiujący.


==== Ustawianie iteratorów ====

=== begin ===
  * iterator begin ();
  * const_iterator begin () const;

Zwraca iterator wskazujący na pierwszy element.

=== end ===
  * iterator end ();
  * const_iterator end () const;

Zwraca iterator wskazujący na element za ostatnim.

=== rbegin ===
  * reverse_iterator rbegin();
  * const_reverse_iterator rbegin() const;

Zwraca odwrotny iterator wskazujący na ostatni element.

=== rend ===
  * reverse_iterator rend();
  * const_reverse_iterator rend() const;

Zwraca odwrotny iterator wskazujący na element przed pierwszym elementem.


==== Zliczanie elementów ====

  * bool empty() const                       - zwraca true, gdy multizbiór jest pusty, w przeciwnym przypadku false
  * size_type count(const key_type& k) const - zwraca liczbę wystąpień elementów o zadanym kluczu
  * size_type size() const                   - podaje liczbę elementów w multizbiorze	 

==== Wyszukiwanie elementów ====

  * iterator find(const key_type& k) const 	  - Zwraca pierwszy element o zadanym kluczu.
  * iterator lower_bound(const key_type& k) const - Zwraca pierwszy element którego klucz nie jest mniejszy od zadanego klucza.
  * iterator upper_bound(const key_type& k) const - Zwraca pierwszy element, którego klucz jest większy od zadanego.

Jeśli nie istnieje taki element to funkcje te zwracają end()

  * pair<iterator, iterator> equal_range(const key_type& k) const - Zwraca zakres elementów o zadanym kluczu.

Zakres elementów można też uzyskać za pomocą: pair<iterator, iterator>( multiset::lower_bound(key), multiset::upper_bound(key))

==== Dodawanie elementów ====

  * iterator insert(const value_type& x) 	       - dodaje x do multizbioru.
  * iterator insert(iterator pos, const value_type& x) - dodaje x do multizbioru, używając pos jako wskazanie gdzie dany element ma zostać wstawiony
  * template <class InputIterator> 
             void insert(InputIterator, InputIterator) - dodaje elementy z zadanego zakresu


==== Usuwanie elementów ====

  * iterator erase(iterator pos) 	          - usuwa element wskazywany przez iterator (zwraca iterator na element za osuniętym)
  * size_type erase(const key_type& k) 	          - usuwa wszystkie elementy o podanym kluczu
  * iterator erase(iterator first, iterator last) - usuwa elementy podanego zakresu <first,last) (zwraca iterator na element za ostatnim usunietym)
  * void clear()                                  - usuwa wszystkie elementy

Aby usunąć jeden element o zadanym kluczu należy użyć następującej konstrukcji: erase( find(k) )

===== Przykładowy program z zastosowaniem =====

{{:opis_kontenera:multiset.cpp|Przykładowy program pokazujący działanie multiset.}}