Compartilhar via


Classe multimap

A classe de multimap da biblioteca padrão C++ é usada para o armazenamento e a recuperação de dados de uma coleção em que cada elemento é um par que contém um valor de dados e uma chave de classificação. O valor da chave não precisa ser exclusivo e é usado para ordenar os dados automaticamente. O valor de um elemento em um multimapa, mas não seu valor de chave associado, pode ser alterado diretamente. Em vez disso, os valores de chave associados aos elementos antigos devem ser excluídos e os novos valores de chave associados aos novos elementos inseridos.

Sintaxe

template <class Key,
    class Type,
    class Traits=less <Key>,
    class Allocator=allocator <pair  <const Key, Type>>>
class multimap;

Parâmetros

Key
O tipo de dados da chave a ser armazenado no multimapa.

Type
O tipo de dados do elemento a ser armazenado no multimapa.

Traits
O tipo que fornece um objeto de função que pode comparar dois valores de elemento como chaves de classificação para determinar sua ordem relativa no multimapa. O predicado binário less<Key> é o valor padrão.

No C++ 14, você pode habilitar a pesquisa heterogênea ao especificar o predicado std::less<> ou o std::greater<>, que não tem nenhum parâmetro de tipo. Para obter mais informações, consulte Pesquisa heterogênea em contêineres associativos

Allocator
O tipo que representa o objeto de alocador armazenado que encapsula detalhes sobre a alocação e a desalocação do mapa da memória. Esse argumento é opcional e o valor padrão é allocator<pair <const Key, Type> >.

Comentários

A classe de multimap da biblioteca padrão C++ é

  • Um contêiner associativo, que é um contêiner de tamanho variável que oferece suporte à recuperação eficiente dos valores de elemento com base em um valor de chave associado.

  • Reversível, pois fornece iteradores bidirecionais para acessar seus elementos.

  • Classificada, pois seus elementos são ordenados por valores de chave no contêiner, de acordo com uma função de comparação especificada.

  • Múltipla, pois seus elementos não precisam ter uma chave única para que um valor de chave possa ter muitos valores de dados de elemento associados a ele.

  • Um contêiner de par associativo, pois seus valores de dados de elemento são distintos de seus valores de chave.

  • Um modelo de classe, pois a funcionalidade fornecida por ela é genérica e, portanto, independente do tipo de dados específico contido como elementos ou chaves. Os tipos de dados a serem usados para elementos e chaves são especificados como parâmetros no modelo de classe juntamente com o alocador e a função de comparação.

O iterador fornecido pela classe de mapa é um iterador bidirecional, mas as funções membro de classe insert e multimap têm versões que usam como parâmetros de modelo um iterador de entrada mais fraco, cujos requisitos de funcionalidade são mais minimalistas do que aqueles assegurados pela classe de iteradores bidirecionais. Os conceitos de iterador diferente formam uma família relacionada por refinamentos em sua funcionalidade. Cada conceito de iterador tem seu próprio conjunto de requisitos e os algoritmos que funcionam com eles devem limitar suas suposições para os requisitos fornecidos por esse tipo de iterador. Pode ser pressuposto que um iterador de entrada possa ser desreferenciado para fazer referência a algum objeto e que possa ser incrementado para o próximo iterador na sequência. Esse é um conjunto mínimo de funcionalidade, mas é suficiente para poder expressar de forma significativa um intervalo de iteradores [First, Last) no contexto de funções membro da classe.

A escolha do tipo de contêiner deve se basear, de modo geral, no tipo de pesquisa e inserção exigido pelo aplicativo. Os contêineres associativos são otimizados para as operações de pesquisa, inserção e remoção. As funções membro que oferecem suporte explicitamente a essas operações são eficientes, executando-as em um tempo que está na média proporcional para o logaritmo do número de elementos no contêiner. Inserir de elementos não invalida iteradores e remover elementos invalida apenas os iteradores que apontavam os elementos removidos.

O multimap deve ser o contêiner associativo escolhido quando as condições que associam os valores às respectivas chaves forem atendidas pelo aplicativo. Um modelo para esse tipo de estrutura é uma lista ordenada de palavras-chave com valores de cadeia de caracteres associados fornecidos, por exemplo, definições, em que as palavras nem sempre foram definidas exclusivamente. Se, em vez disso, as palavras-chave foram definidas exclusivamente para que essas chaves fossem exclusivas, um mapa seria o contêiner ideal. Se, por outro lado, apenas as listas de palavras foram sendo armazenadas, um conjunto seria o contêiner correto. Se não foram permitidas as várias ocorrências das palavras, um multiset seria a estrutura de contêiner apropriada.

A multimap ordena a sequência que controla chamando um objeto de função armazenado do tipo key_compare. Esse objeto armazenado é uma função de comparação que pode ser acessada chamando a função de membro key_comp. De modo geral, os elementos precisam ser simplesmente menores que os comparáveis para estabelecer essa ordem: desse modo, considerando dois elementos, pode ser determinado que, ou eles são equivalentes (no sentido de que nenhum deles é menor que o outro), ou que um é menor que o outro. Isso resulta em uma ordenação entre os elementos não equivalentes. Fazendo uma observação mais técnica, a função de comparação é um predicado binário que induz a uma ordenação fraca restrita no sentido matemático padrão. Um predicado binário f(x,y) é um objeto de função que possui dois objetos de argumento x e y e um valor retornado de true ou false. Uma ordenação imposta em um conjunto será uma ordenação fraca restrita se o predicado binário for irreflexivo, antissimétrico e transitivo, e se a equivalência for transitiva, onde dois objetos x e y são definidos para serem equivalentes quando ambos f(x,y) e f(y,x) são false. Se a condição mais forte de igualdade entre as chaves substituir essa equivalência, a ordenação será total (no sentido de que todos os elementos serão ordenados um em relação ao outro) e as chaves correspondentes não poderão ser diferenciadas uma da outra.

No C++ 14, você pode habilitar a pesquisa heterogênea ao especificar o predicado std::less<> ou o std::greater<>, que não tem nenhum parâmetro de tipo. Confira Pesquisa Heterogênea em Contêineres Associativos para saber mais.

Membros

Construtores

Construtor Descrição
multimap Constrói um multimap que está vazio ou que é uma cópia de todo ou parte de algum outro multimap.

Typedefs

Nome do tipo Descrição
allocator_type Um tipo que representa a classe allocator para o objeto multimap.
const_iterator Um tipo que fornece um iterador bidirecional que pode ler um elemento const no multimap.
const_pointer Um tipo que fornece um ponteiro para um elemento const em um multimap.
const_reference Um tipo que fornece uma referência para um elemento const armazenado em um multimap para leitura e execução de operações const.
const_reverse_iterator Um tipo que fornece um iterador bidirecional que pode ler qualquer elemento const no multimap.
difference_type Um tipo de inteiro com sinal que pode ser usado para representar o número de elementos de um multimap em um intervalo entre os elementos apontado pelos iteradores.
iterator Um tipo que fornece a diferença entre dois iteradores que se referem a elementos no mesmo multimap.
key_compare Um tipo que fornece um objeto de função que pode comparar duas chaves de classificação para determinar a ordem relativa de dois elementos no multimap.
key_type Um tipo que descreve o objeto de chave de classificação que forma cada elemento do multimap.
mapped_type Um tipo que representa o tipo de dados armazenado em um multimap.
pointer Um tipo que fornece um ponteiro para um elemento const em um multimap.
reference Um tipo que fornece uma referência a um elemento armazenado em um multimap.
reverse_iterator Um tipo que fornece um iterador bidirecional que pode ler ou modificar um elemento em um multimap invertido.
size_type Um tipo de inteiro sem sinal que fornece um ponteiro para um elemento const em um multimap.
value_type Um tipo que fornece um objeto de função que pode comparar dois elementos como chaves de classificação para determinar sua ordem relativa no multimap.

Funções de membro

Função de membro Descrição
begin Retorna um iterador que trata o primeiro elemento no multimap.
cbegin Retorna um iterador multimap que trata o primeiro elemento no const.
cend Retorna um iterador const que trata o local após o último elemento em um multimap.
clear Apaga todos os elementos de um multimap.
containsC++20 Verifica se há um elemento com a chave especificada no multimap.
count Retorna o número de elementos em um multimap cuja chave corresponde a uma chave especificada pelo parâmetro.
crbegin Retorna um iterador const que trata o primeiro elemento em um multimap invertido.
crend Retorna um iterador const que trata o local após o último elemento em um multimap invertido.
emplace Insere um elemento construído adequadamente em um multimap.
emplace_hint Insere um elemento construído adequadamente em um multimap, com uma dica de posicionamento
empty Testa se multimap está vazio.
end Retorna um iterador que trata o local após o último elemento em um multimap.
equal_range Localiza o intervalo de elementos em que a chave do elemento corresponde a um valor especificado.
erase Remove um elemento ou um intervalo de elementos em um multimap das posições especificadas ou remove elementos que correspondem a uma chave especificada.
find Retorna um iterador que trata o primeiro local de um elemento em um multimap que tem uma chave equivalente a uma chave especificada.
get_allocator Retorna uma cópia do objeto allocator usada para construir o multimap.
insert Insere um elemento ou um intervalo de elementos em um multimap.
key_comp Recupera uma cópia do objeto de comparação usada para ordenar chaves em um multimap.
lower_bound Retorna um iterador para o primeiro elemento em um multimap com uma chave que é igual ou maior que uma chave especificada.
max_size Retorna o comprimento máximo do multimap.
rbegin Retorna um iterador que trata o primeiro elemento em um multimap invertido.
rend Retorna um iterador que trata o local após o último elemento em um multimap invertido.
size Retorna o número de elementos no multimap.
swap Troca os elementos de dois multimaps.
upper_bound Retorna um iterador para o primeiro elemento em um multimap com uma chave que é maior que uma chave especificada.
value_comp A função membro retorna um objeto de função que determina a ordem dos elementos em um multimap comparando os respectivos valores de chave.
Operador Descrição
operator= Substitui os elementos de um multimap por uma cópia de outro multimap.

Requisitos

Cabeçalho: <map>

Namespace: std

Os pares (chave, valor) são armazenados em um multimap como objetos do tipo pair. A classe de par exige o cabeçalho <utility>, que é automaticamente incluído por <map>.

multimap::allocator_type

Um tipo que representa a classe do alocador para o objeto multimap.

typedef Allocator allocator_type;

Exemplo

Veja o exemplo de get_allocator para obter um exemplo que usa allocator_type.

multimap::begin

Retorna um iterador que trata o primeiro elemento no multimap.

const_iterator begin() const;

iterator begin();

Valor de retorno

Um iterador bidirecional que trata o primeiro elemento no multimap ou o local após um multimap vazio.

Exemplo

// multimap_begin.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;

   multimap <int, int> :: iterator m1_Iter;
   multimap <int, int> :: const_iterator m1_cIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 0, 0 ) );
   m1.insert ( Int_Pair ( 1, 1 ) );
   m1.insert ( Int_Pair ( 2, 4 ) );

   m1_cIter = m1.begin ( );
   cout << "The first element of m1 is " << m1_cIter -> first << endl;

   m1_Iter = m1.begin ( );
   m1.erase ( m1_Iter );

   // The following 2 lines would err as the iterator is const
   // m1_cIter = m1.begin ( );
   // m1.erase ( m1_cIter );

   m1_cIter = m1.begin( );
   cout << "First element of m1 is now " << m1_cIter -> first << endl;
}
The first element of m1 is 0
First element of m1 is now 1

multimap::cbegin

Retorna um iterador const que trata o primeiro elemento no intervalo.

const_iterator cbegin() const;

Valor de retorno

Um iterador de acesso bidirecional const que aponta o primeiro elemento do intervalo ou o local logo após o fim de um intervalo vazio (para um intervalo vazio, cbegin() == cend()).

Comentários

Com o valor retornado de cbegin, os elementos no intervalo não podem ser modificados.

Você pode usar essa função membro no lugar da função membro begin(), de modo a garantir que o valor de retorno seja const_iterator. Normalmente, é usada em conjunto com a palavra-chave de dedução de tipo auto, conforme mostrado no exemplo a seguir. No exemplo, considere Container como um contêiner modificável (não const) de qualquer tipo, que dá suporte para begin() e cbegin().

auto i1 = Container.begin();
// i1 is Container<T>::iterator
auto i2 = Container.cbegin();

// i2 is Container<T>::const_iterator

multimap::cend

Retorna um iterador const que trata o local logo após o último elemento em um intervalo.

const_iterator cend() const;

Valor de retorno

Um iterador de acesso bidirecional const que aponta para além do fim do intervalo.

Comentários

cend é usado para testar se um iterador passou do fim de seu intervalo.

Você pode usar essa função membro no lugar da função membro end(), de modo a garantir que o valor de retorno seja const_iterator. Normalmente, é usada em conjunto com a palavra-chave de dedução de tipo auto, conforme mostrado no exemplo a seguir. No exemplo, considere Container como um contêiner modificável (não const) de qualquer tipo, que dá suporte para end() e cend().

auto i1 = Container.end();
// i1 is Container<T>::iterator
auto i2 = Container.cend();

// i2 is Container<T>::const_iterator

O valor retornado por cend não deve ser desreferenciado.

multimap::clear

Apaga todos os elementos de um multimap.

void clear();

Exemplo

O exemplo a seguir demonstra o uso da função de membro multimap::clear.

// multimap_clear.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap<int, int> m1;
   multimap<int, int>::size_type i;
   typedef pair<int, int> Int_Pair;

   m1.insert(Int_Pair(1, 1));
   m1.insert(Int_Pair(2, 4));

   i = m1.size();
   cout << "The size of the multimap is initially "
        << i << "." << endl;

   m1.clear();
   i = m1.size();
   cout << "The size of the multimap after clearing is "
        << i << "." << endl;
}
The size of the multimap is initially 2.
The size of the multimap after clearing is 0.

multimap::const_iterator

Um tipo que fornece um iterador bidirecional que pode ler um elemento const no multimap.

typedef implementation-defined const_iterator;

Comentários

Um tipo const_iterator não pode ser usado para modificar o valor de um elemento.

O const_iterator definido por pontos multimap a objetos de value_type, que são do tipo pair<const Key, Type>. O valor da chave está disponível por meio do primeiro par de membros e o valor do elemento mapeado está disponível por meio do segundo membro do par.

Para desreferenciar um const_iterator cIter apontamento para um elemento em um multimap, use o -> operador.

Para acessar o valor de chave do elemento, use cIter->first, que é equivalente a (*cIter).first. Para acessar o valor dos dados mapeados do elemento, use cIter->second, que é equivalente a (*cIter).second.

Exemplo

Veja o exemplo de begin para obter um exemplo que usa const_iterator.

multimap::const_pointer

Um tipo que fornece um ponteiro para um elemento const em um multimap.

typedef typename allocator_type::const_pointer const_pointer;

Comentários

Um tipo const_pointer não pode ser usado para modificar o valor de um elemento.

Na maioria dos casos, um iterator deve ser usado para acessar os elementos em um objeto multimap.

multimap::const_reference

Um tipo que fornece uma referência para um elemento const armazenado em um multimap para leitura e execução de operações const.

typedef typename allocator_type::const_reference const_reference;

Exemplo

// multimap_const_ref.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );

   // Declare and initialize a const_reference &Ref1
   // to the key of the first element
   const int &Ref1 = ( m1.begin( ) -> first );

   // The following line would cause an error because the
   // non-const_reference can't be used to access the key
   // int &Ref1 = ( m1.begin( ) -> first );

   cout << "The key of the first element in the multimap is "
        << Ref1 << "." << endl;

   // Declare and initialize a reference &Ref2
   // to the data value of the first element
   int &Ref2 = ( m1.begin( ) -> second );

   cout << "The data value of the first element in the multimap is "
        << Ref2 << "." << endl;
}
The key of the first element in the multimap is 1.
The data value of the first element in the multimap is 10.

multimap::const_reverse_iterator

Um tipo que fornece um iterador bidirecional que pode ler qualquer elemento const no multimap.

typedef std::reverse_iterator<const_iterator> const_reverse_iterator;

Comentários

Um tipo const_reverse_iterator não pode modificar o valor de um elemento e é usado para iterar o multimap invertido.

O const_reverse_iterator definido por pontos multimap a objetos de value_type, que são do tipo pair<const Key, Type>. O valor da chave está disponível por meio do primeiro par de membros e o valor do elemento mapeado está disponível por meio do segundo membro do par.

Para desreferenciar um const_reverse_iterator crIter apontamento para um elemento em um multimap, use o -> operador.

Para acessar o valor de chave do elemento, use crIter->first, que é equivalente a (*crIter).first. Para acessar o valor dos dados mapeados do elemento, use crIter->second, que é equivalente a (*crIter).first.

Exemplo

Veja o exemplo de rend que demonstra como declarar e usar const_reverse_iterator.

multimap::contains

Verifica se há um elemento com a chave especificada no multimap.

bool contains(const Key& key) const;
template<class K> bool contains(const K& key) const;

Parâmetros

K
Tipo da chave.

key
O valor-chave do elemento a ser procurado.

Valor de retorno

true se o elemento for encontrado no contêiner; caso contrário, será false.

Comentários

contains() é novo em C++20. Para usá-lo, especifique a opção do compilador /std:c++20 ou posterior.

template<class K> bool contains(const K& key) const só participará da resolução de sobrecarga se key_compare for transparente. Confira Pesquisa heterogênea em contêineres associativos para obter mais informações.

Exemplo

// Requires /std:c++20 or /std:c++latest
#include <map>
#include <string>
#include <iostream>
#include <functional>

int main()
{
    std::multimap<int, bool> m = {{0, false}, {1, true}};

    std::cout << std::boolalpha; // so booleans show as 'true' or 'false'
    std::cout << m.contains(1) << '\n';
    std::cout << m.contains(2) << '\n';

    // call template function
    std::multimap<std::string, int, std::less<>> m2 = {{"ten", 10}, {"twenty", 20}, {"thirty", 30}};
    std::cout << m2.contains("ten");

    return 0;
}
true
false
true

multimap::count

Retorna o número de elementos em um multimap cuja chave corresponde a uma chave especificada pelo parâmetro.

size_type count(const Key& key) const;

Parâmetros

key
A chave dos elementos a serem correspondidos do multimap.

Valor de retorno

O número de elementos cujas chaves de classificação correspondem à chave de parâmetro; 0 se o multimap não contiver um elemento com uma chave correspondente.

Comentários

A função membro retorna o número de elementos no intervalo

lower_bound(key), upper_bound(key)

que tem um valor de chave key.

Exemplo

O exemplo a seguir demonstra o uso da função membro multimap::count.

// multimap_count.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
    using namespace std;
    multimap<int, int> m1;
    multimap<int, int>::size_type i;
    typedef pair<int, int> Int_Pair;

    m1.insert(Int_Pair(1, 1));
    m1.insert(Int_Pair(2, 1));
    m1.insert(Int_Pair(1, 4));
    m1.insert(Int_Pair(2, 1));

    // Elements don't need to have unique keys in multimap,
    // so duplicates are allowed and counted
    i = m1.count(1);
    cout << "The number of elements in m1 with a sort key of 1 is: "
         << i << "." << endl;

    i = m1.count(2);
    cout << "The number of elements in m1 with a sort key of 2 is: "
         << i << "." << endl;

    i = m1.count(3);
    cout << "The number of elements in m1 with a sort key of 3 is: "
         << i << "." << endl;
}
The number of elements in m1 with a sort key of 1 is: 2.
The number of elements in m1 with a sort key of 2 is: 2.
The number of elements in m1 with a sort key of 3 is: 0.

multimap::crbegin

Retorna um iterador const que trata o primeiro elemento em um multimap invertido.

const_reverse_iterator crbegin() const;

Valor de retorno

Um iterador bidirecional invertido const que trata o primeiro elemento em um multimap invertido ou que endereça o que foi o último elemento no multimap não invertido.

Comentários

crbegin é usado com um multimap invertido, assim como begin é usado com um multimap.

Com o valor retornado crbegin, o objeto multimap não pode ser modificado.

crbegin pode ser usado para iterar em um multimap no sentido inverso.

Exemplo

// multimap_crbegin.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;

   multimap <int, int> :: const_reverse_iterator m1_crIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );

   m1_crIter = m1.crbegin( );
   cout << "The first element of the reversed multimap m1 is "
        << m1_crIter -> first << "." << endl;
}
The first element of the reversed multimap m1 is 3.

multimap::crend

Retorna um iterador const que trata o local após o último elemento em um multimap invertido.

const_reverse_iterator crend() const;

Valor de retorno

Um iterador bidirecional inverso const que trata a localização que vem após o último elemento em um multimap invertido (o local que precedeu o primeiro elemento no multimap não invertido).

Comentários

crend é usado com um multimap invertido, assim como multimap::end é usado com um multimap.

Com o valor retornado crend, o objeto multimap não pode ser modificado.

crend pode ser usado para testar se um iterador inverso alcançou o final de sua multimap.

O valor retornado por crend não deve ser desreferenciado.

Exemplo

// multimap_crend.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;

   multimap <int, int> :: const_reverse_iterator m1_crIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );

   m1_crIter = m1.crend( );
   m1_crIter--;
   cout << "The last element of the reversed multimap m1 is "
        << m1_crIter -> first << "." << endl;
}
The last element of the reversed multimap m1 is 1.

multimap::difference_type

Um tipo de inteiro com sinal que pode ser usado para representar o número de elementos de um multimap em um intervalo entre os elementos apontado pelos iteradores.

typedef typename allocator_type::difference_type difference_type;

Comentários

difference_type é o tipo retornado ao subtrair ou incrementar por meio de iteradores do contêiner. difference_type geralmente é usado para representar o número de elementos no intervalo [first, last) entre os iteradores first e last, inclui o elemento apontado por first e o intervalo de elementos até, mas sem incluir, o elemento apontado por last.

Embora difference_type esteja disponível para todos os iteradores que atendem aos requisitos de um iterador de entrada, que inclui a classe de iteradores bidirecionais com suporte pelos contêineres reversíveis, como conjunto, a subtração entre iteradores só tem suporte pelos iteradores de acesso aleatório fornecidos por um contêiner de acesso aleatório, como vetor.

Exemplo

// multimap_diff_type.cpp
// compile with: /EHsc
#include <iostream>
#include <map>
#include <algorithm>

int main( )
{
   using namespace std;
   multimap <int, int> m1;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 3, 20 ) );

   // The following will insert as multimap keys are not unique
   m1.insert ( Int_Pair ( 2, 30 ) );

   multimap <int, int>::iterator m1_Iter, m1_bIter, m1_eIter;
   m1_bIter = m1.begin( );
   m1_eIter = m1.end( );

   // Count the number of elements in a multimap
   multimap <int, int>::difference_type  df_count = 0;
   m1_Iter = m1.begin( );
   while ( m1_Iter != m1_eIter )
   {
      df_count++;
      m1_Iter++;
   }

   cout << "The number of elements in the multimap m1 is: "
        << df_count << "." << endl;
}
The number of elements in the multimap m1 is: 4.

multimap::emplace

Insere um elemento criado no local (nenhuma operação de cópia ou movimentação é realizada).

template <class... Args>
iterator emplace(Args&&... args);

Parâmetros

args
Os argumentos encaminhados para construir um elemento a ser inserido na multimap.

Valor de retorno

Um iterador para o elemento recém-inserido.

Comentários

Nenhuma referência a elementos de contêiner é invalidada por essa função, mas ela pode invalidar todos os iteradores no contêiner.

Se uma exceção for gerada durante a inserção, o contêiner permanecerá inalterado e a exceção será gerada novamente.

O value_type de um elemento é um par, de forma que o valor de um elemento será um par ordenado com o primeiro componente igual ao valor de chave e o segundo componente igual ao valor dos dados do elemento.

Exemplo

// multimap_emplace.cpp
// compile with: /EHsc
#include <map>
#include <string>
#include <iostream>

using namespace std;

template <typename M> void print(const M& m) {
    cout << m.size() << " elements: " << endl;

    for (const auto& p : m) {
        cout << "(" << p.first <<  "," << p.second << ") ";
    }

    cout << endl;
}

int main()
{
    multimap<string, string> m1;

    m1.emplace("Anna", "Accounting");
    m1.emplace("Bob", "Accounting");
    m1.emplace("Carmine", "Engineering");

    cout << "multimap modified, now contains ";
    print(m1);
    cout << endl;

    m1.emplace("Bob", "Engineering");

    cout << "multimap modified, now contains ";
    print(m1);
    cout << endl;
}

multimap::emplace_hint

Insere um elemento criado no local (nenhuma operação de cópia ou movimentação é realizada), com uma dica de posicionamento.

template <class... Args>
iterator emplace_hint(
    const_iterator where,
    Args&&... args);

Parâmetros

args
Os argumentos encaminhados para construir um elemento a ser inserido na multimap.

where
O local a partir do qual se começa a procurar pelo ponto de inserção correto. (Se esse ponto preceder imediatamente where, a inserção poderá ocorrer em um tempo constante amortizado, em vez de no tempo logarítmico.)

Valor de retorno

Um iterador para o elemento recém-inserido.

Comentários

Nenhuma referência a elementos de contêiner é invalidada por essa função, mas ela pode invalidar todos os iteradores no contêiner.

Durante o posicionamento, se uma exceção for lançada, o estado do contêiner não será modificado.

O value_type de um elemento é um par, de forma que o valor de um elemento será um par ordenado com o primeiro componente igual ao valor de chave e o segundo componente igual ao valor dos dados do elemento.

Para obter um exemplo de código, consulte map::emplace_hint.

multimap::empty

Testa se multimap está vazio.

bool empty() const;

Valor de retorno

true se multimap for vazio; false se multimap não for vazio.

Exemplo

// multimap_empty.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1, m2;

   typedef pair <int, int> Int_Pair;
   m1.insert ( Int_Pair ( 1, 1 ) );

   if ( m1.empty( ) )
      cout << "The multimap m1 is empty." << endl;
   else
      cout << "The multimap m1 is not empty." << endl;

   if ( m2.empty( ) )
      cout << "The multimap m2 is empty." << endl;
   else
      cout << "The multimap m2 is not empty." << endl;
}
The multimap m1 is not empty.
The multimap m2 is empty.

multimap::end

Retorna o iterador que ultrapassa o fim.

const_iterator end() const;

iterator end();

Valor de retorno

O iterador que ultrapassa o fim. Se o multimap estiver vazio, então multimap::end() == multimap::begin().

Comentários

end é usado para testar se um iterador ultrapassou o fim do seu mapa multimap.

O valor retornado por end não deve ser desreferenciado.

Para obter um exemplo de código, consulte multimap::find.

multimap::equal_range

Localiza o intervalo de elementos em que a chave do elemento corresponde a um valor especificado.

pair <const_iterator, const_iterator> equal_range (const Key& key) const;

pair <iterator, iterator> equal_range (const Key& key);

Parâmetros

key
A chave do argumento a ser comparada com a chave de classificação de um elemento do multimap que está sendo pesquisado.

Valor de retorno

Um par de iteradores em que o primeiro é o lower_bound da chave e o segundo é o upper_bound da chave.

Para acessar o primeiro iterador de um par pr retornado pela função membro, use pr.first e para desreferenciar o iterador de limite inferior, use *(pr.first). Para acessar o segundo iterador de um par pr retornado pela função membro, use pr.second e para desreferenciar o iterador de limite inferior, use *(pr.second).

Exemplo

// multimap_equal_range.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   typedef multimap <int, int, less<int> > IntMMap;
   IntMMap m1;
   multimap <int, int> :: const_iterator m1_RcIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );

   pair <IntMMap::const_iterator, IntMMap::const_iterator> p1, p2;
   p1 = m1.equal_range( 2 );

   cout << "The lower bound of the element with "
        << "a key of 2 in the multimap m1 is: "
        << p1.first -> second << "." << endl;

   cout << "The upper bound of the element with "
        << "a key of 2 in the multimap m1 is: "
        << p1.second -> second << "." << endl;

   // Compare the upper_bound called directly
   m1_RcIter = m1.upper_bound( 2 );

   cout << "A direct call of upper_bound( 2 ) gives "
        << m1_RcIter -> second << "," << endl
        << "matching the 2nd element of the pair "
        << "returned by equal_range( 2 )." << endl;

   p2 = m1.equal_range( 4 );

   // If no match is found for the key,
   // both elements of the pair return end( )
   if ( ( p2.first == m1.end( ) ) && ( p2.second == m1.end( ) ) )
      cout << "The multimap m1 doesn't have an element "
           << "with a key less than 4." << endl;
   else
      cout << "The element of multimap m1 with a key >= 40 is: "
           << p1.first -> first << "." << endl;
}
The lower bound of the element with a key of 2 in the multimap m1 is: 20.
The upper bound of the element with a key of 2 in the multimap m1 is: 30.
A direct call of upper_bound( 2 ) gives 30,
matching the 2nd element of the pair returned by equal_range( 2 ).
The multimap m1 doesn't have an element with a key less than 4.

multimap::erase

Remove um elemento ou um intervalo de elementos em um multimap das posições especificadas ou remove elementos que correspondem a uma chave especificada.

iterator erase(
    const_iterator Where);

iterator erase(
    const_iterator First,
    const_iterator Last);

size_type erase(
    const key_type& Key);

Parâmetros

Where
A posição do elemento a ser removido.

First
A posição do primeiro elemento a ser removido.

Last
A posição logo após o último elemento a ser removido.

Key
A chave de elementos a serem removidos.

Valor de retorno

Para as duas primeiras funções membro, um iterador bidirecional que designa o primeiro elemento restante além de quaisquer elementos removidos ou um elemento que será o final do mapa, se esse elemento não existir.

Para a terceira função membro, ele retorna o número de elementos que foram removidos do multimap.

Comentários

Para obter um exemplo de código, consulte map::erase.

multimap::find

Retorna um iterador que aponta para o primeiro local de um elemento em um multimap com uma chave equivalente a uma chave especificada.

iterator find(const Key& key);

const_iterator find(const Key& key) const;

Parâmetros

key
O valor da chave a ser correspondido pela chave de classificação de um elemento do multimap que está sendo pesquisado.

Valor de retorno

Um iterador que se refere ao local de um elemento com uma chave especificada ou o local que substitui o último elemento em multimap (multimap::end()) se nenhuma correspondência for encontrada para a chave.

Comentários

A função membro retorna um iterador que se refere a um elemento do multimap, cuja chave é equivalente à chave de argumento em um predicado binário que induz uma ordenação com base em uma relação de comparação menor.

Se o valor retornado de find for atribuído a um const_iterator, o objeto multimap não poderá ser modificado. Se o valor retornado de find for atribuído a um iterator, o objeto multimap pode ser modificado.

Exemplo

// compile with: /EHsc /W4 /MTd
#include <map>
#include <iostream>
#include <vector>
#include <string>
#include <utility>  // make_pair()

using namespace std;

template <typename A, typename B> void print_elem(const pair<A, B>& p) {
    cout << "(" << p.first << ", " << p.second << ") ";
}

template <typename T> void print_collection(const T& t) {
    cout << t.size() << " elements: ";

    for (const auto& p : t) {
        print_elem(p);
    }
    cout << endl;
}

template <typename C, class T> void findit(const C& c, T val) {
    cout << "Trying find() on value " << val << endl;
    auto result = c.find(val);
    if (result != c.end()) {
        cout << "Element found: "; print_elem(*result); cout << endl;
    } else {
        cout << "Element not found." << endl;
    }
}

int main()
{
    multimap<int, string> m1({ { 40, "Zr" }, { 45, "Rh" } });
    cout << "The starting multimap m1 is (key, value):" << endl;
    print_collection(m1);

    vector<pair<int, string>> v;
    v.push_back(make_pair(43, "Tc"));
    v.push_back(make_pair(41, "Nb"));
    v.push_back(make_pair(46, "Pd"));
    v.push_back(make_pair(42, "Mo"));
    v.push_back(make_pair(44, "Ru"));
    v.push_back(make_pair(44, "Ru")); // attempt a duplicate

    cout << "Inserting the following vector data into m1:" << endl;
    print_collection(v);

    m1.insert(v.begin(), v.end());

    cout << "The modified multimap m1 is (key, value):" << endl;
    print_collection(m1);
    cout << endl;
    findit(m1, 45);
    findit(m1, 6);
}

multimap::get_allocator

Retorna uma cópia do objeto alocador usado para construir o multimap.

allocator_type get_allocator() const;

Valor de retorno

O alocador usado pelo multimap.

Comentários

Alocadores para a classe multimap especificam como a classe gerencia o armazenamento. Os alocadores padrão fornecidos com as classes de contêiner da Biblioteca Padrão C++ são suficientes para a maioria das necessidades de programação. Gravando e usando sua própria classe de alocador é um tópico avançado do C++.

Exemplo

// multimap_get_allocator.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int>::allocator_type m1_Alloc;
   multimap <int, int>::allocator_type m2_Alloc;
   multimap <int, double>::allocator_type m3_Alloc;
   multimap <int, int>::allocator_type m4_Alloc;

   // The following lines declare objects
   // that use the default allocator.
   multimap <int, int> m1;
   multimap <int, int, allocator<int> > m2;
   multimap <int, double, allocator<double> > m3;

   m1_Alloc = m1.get_allocator( );
   m2_Alloc = m2.get_allocator( );
   m3_Alloc = m3.get_allocator( );

   cout << "The number of integers that can be allocated"
        << endl << "before free memory is exhausted: "
        << m2.max_size( ) << ".\n" << endl;

   cout << "The number of doubles that can be allocated"
        << endl << "before free memory is exhausted: "
        << m3.max_size( ) <<  ".\n" << endl;

   // The following line creates a multimap m4
   // with the allocator of multimap m1.
   map <int, int> m4( less<int>( ), m1_Alloc );

   m4_Alloc = m4.get_allocator( );

   // Two allocators are interchangeable if
   // storage allocated from each can be
   // deallocated via the other
   if( m1_Alloc == m4_Alloc )
   {
      cout << "The allocators are interchangeable."
           << endl;
   }
   else
   {
      cout << "The allocators are not interchangeable."
           << endl;
   }
}

multimap::insert

Insere um elemento ou um intervalo de elementos em um multimap.

// (1) single element
pair<iterator, bool> insert(
    const value_type& Val);

// (2) single element, perfect forwarded
template <class ValTy>
pair<iterator, bool>
insert(
    ValTy&& Val);

// (3) single element with hint
iterator insert(
    const_iterator Where,
    const value_type& Val);

// (4) single element, perfect forwarded, with hint
template <class ValTy>
iterator insert(
    const_iterator Where,
    ValTy&& Val);

// (5) range
template <class InputIterator>
void insert(
    InputIterator First,
    InputIterator Last);

// (6) initializer list
void insert(
    initializer_list<value_type>
IList);

Parâmetros

Val
O valor de um elemento a ser inserido em multimap.

Where
O local a partir do qual se começa a procurar pelo ponto de inserção correto. (Se esse ponto preceder imediatamente Where, a inserção poderá ocorrer em um tempo constante amortizado, em vez de no tempo logarítmico.)

ValTy
O parâmetro de modelo que especifica o tipo de argumento que o mapa pode usar para construir um elemento de value_type e encaminhar perfeitamente Val como um argumento.

First
A posição do primeiro elemento a ser copiado.

Last
A posição imediatamente após o último elemento a ser copiado.

InputIterator
O argumento da função de modelo que atende aos requisitos de um inputiterador que aponta para elementos de um tipo que pode ser usado para construir objetos value_type.

IList
O initializer_list para o qual copiar os elementos.

Valor de retorno

As funções do membro de inserção do elemento único, (1) e (2), retornam um iterador para a posição em que o novo elemento foi inserido em multimap.

As funções membro de inserção de elemento único, (3) e (4), retornam um iterador para a posição em que o novo elemento foi inserido na multimap.

Comentários

Nenhum ponteiro ou referência é invalidado por esta função, mas ela pode invalidar todos os iteradores para o contêiner.

Durante a inserção de apenas um elemento, se uma exceção for lançada, o estado do contêiner não será modificado. Durante a inserção de vários elementos, se uma exceção for lançada, o contêiner será deixado em um estado não especificado, mas válido.

O value_type de um contêiner é um typedef que pertence ao contêiner e para o mapa, multimap<K, V>::value_type é pair<const K, V>. O valor de um elemento é um par ordenado no qual o primeiro componente é igual ao valor chave e o segundo componente é igual ao valor dos dados do elemento.

A função membro de intervalo (5) insere a sequência de valores de elemento em um multimap que corresponde a cada elemento tratado por um iterador no intervalo [First, Last); portanto, Last não é inserido. A função de membro do contêiner end() refere-se à posição logo após o último elemento no contêiner, por exemplo, a instrução m.insert(v.begin(), v.end()); insere todos os elementos de v em m.

A função membro da lista do inicializador (6) usa um initializer_list para copiar elementos para um mapa.

Para inserir um elemento construído no lugar (ou seja, sem a realização de operação de cópia ou movimentação), confira multimap::emplace e multimap::emplace_hint.

Exemplo

// multimap_insert.cpp
// compile with: /EHsc
#include <map>
#include <iostream>
#include <string>
#include <vector>
#include <utility>  // make_pair()

using namespace std;

template <typename M> void print(const M& m) {
    cout << m.size() << " elements: ";

    for (const auto& p : m) {
        cout << "(" << p.first << ", " << p.second << ") ";
    }

    cout << endl;
}

int main()
{
    // insert single values
    multimap<int, int> m1;
    // call insert(const value_type&) version
    m1.insert({ 1, 10 });
    // call insert(ValTy&&) version
    m1.insert(make_pair(2, 20));

    cout << "The original key and mapped values of m1 are:" << endl;
    print(m1);

    // intentionally attempt a duplicate, single element
    m1.insert(make_pair(1, 111));

    cout << "The modified key and mapped values of m1 are:" << endl;
    print(m1);

    // single element, with hint
    m1.insert(m1.end(), make_pair(3, 30));
    cout << "The modified key and mapped values of m1 are:" << endl;
    print(m1);
    cout << endl;

    // The templatized version inserting a jumbled range
    multimap<int, int> m2;
    vector<pair<int, int>> v;
    v.push_back(make_pair(43, 294));
    v.push_back(make_pair(41, 262));
    v.push_back(make_pair(45, 330));
    v.push_back(make_pair(42, 277));
    v.push_back(make_pair(44, 311));

    cout << "Inserting the following vector data into m2:" << endl;
    print(v);

    m2.insert(v.begin(), v.end());

    cout << "The modified key and mapped values of m2 are:" << endl;
    print(m2);
    cout << endl;

    // The templatized versions move-constructing elements
    multimap<int, string>  m3;
    pair<int, string> ip1(475, "blue"), ip2(510, "green");

    // single element
    m3.insert(move(ip1));
    cout << "After the first move insertion, m3 contains:" << endl;
    print(m3);

    // single element with hint
    m3.insert(m3.end(), move(ip2));
    cout << "After the second move insertion, m3 contains:" << endl;
    print(m3);
    cout << endl;

    multimap<int, int> m4;
    // Insert the elements from an initializer_list
    m4.insert({ { 4, 44 }, { 2, 22 }, { 3, 33 }, { 1, 11 }, { 5, 55 } });
    cout << "After initializer_list insertion, m4 contains:" << endl;
    print(m4);
    cout << endl;
}

multimap::iterator

Um tipo que fornece um iterador bidirecional que pode ler ou modificar qualquer elemento em um multimap.

typedef implementation-defined iterator;

Comentários

O iterator definido por pontos multimap a objetos de value_type, que são do tipo pair<const Key, Type>. O valor da chave está disponível por meio do primeiro par de membros e o valor do elemento mapeado está disponível por meio do segundo membro do par.

Para desreferenciar um iterator Iter apontamento para um elemento em um multimap, use o -> operador.

Para acessar o valor de chave do elemento, use Iter->first, que é equivalente a (*Iter).first. Para acessar o valor dos dados mapeados do elemento, use Iter->second, que é equivalente a (*Iter).second.

Um tipo de iterator pode ser usado para modificar o valor de um elemento.

Exemplo

Veja o exemplo de begin que demonstra como declarar e usar iterator.

multimap::key_comp

Recupera uma cópia do objeto de comparação usada para ordenar chaves em um multimap.

key_compare key_comp() const;

Valor de retorno

Retorna o objeto de função que um multimap usa para ordenar os seus elementos.

Comentários

O objeto armazenado define a função membro

bool operator( const Key& x, const Key& y);

que retorna true se x preceder estritamente y na ordem de classificação.

Exemplo

// multimap_key_comp.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;

   multimap <int, int, less<int> > m1;
   multimap <int, int, less<int> >::key_compare kc1 = m1.key_comp( ) ;
   bool result1 = kc1( 2, 3 ) ;
   if( result1 == true )
   {
      cout << "kc1( 2,3 ) returns value of true, "
           << "where kc1 is the function object of m1."
           << endl;
   }
   else
   {
      cout << "kc1( 2,3 ) returns value of false "
           << "where kc1 is the function object of m1."
           << endl;
   }

   multimap <int, int, greater<int> > m2;
   multimap <int, int, greater<int> >::key_compare kc2 = m2.key_comp( );
   bool result2 = kc2( 2, 3 ) ;
   if( result2 == true )
   {
      cout << "kc2( 2,3 ) returns value of true, "
           << "where kc2 is the function object of m2."
           << endl;
   }
   else
   {
      cout << "kc2( 2,3 ) returns value of false, "
           << "where kc2 is the function object of m2."
           << endl;
   }
}
kc1( 2,3 ) returns value of true, where kc1 is the function object of m1.
kc2( 2,3 ) returns value of false, where kc2 is the function object of m2.

multimap::key_compare

Um tipo que fornece um objeto de função que pode comparar duas chaves de classificação para determinar a ordem relativa de dois elementos no multimap.

typedef Traits key_compare;

Comentários

key_compare é um sinônimo do parâmetro de modelo Traits.

Para obter mais informações sobre Traits, confira o tópico multimap Classe.

Exemplo

Veja o exemplo de key_comp que demonstra como declarar e usar key_compare.

multimap::key_type

Um tipo que descreve o objeto de chave de classificação que constitui cada elemento do multimap.

typedef Key key_type;

Comentários

key_type é um sinônimo do parâmetro de modelo Key.

Para obter mais informações sobre Key, consulte a seção Comentários do tópico multimapClasse .

Exemplo

Veja o exemplo de value_type que demonstra como declarar e usar key_type.

multimap::lower_bound

Retorna um iterador para o primeiro elemento em um multimap com uma chave que é igual ou maior que uma chave especificada.

iterator lower_bound(const Key& key);

const_iterator lower_bound(const Key& key) const;

Parâmetros

key
A chave do argumento a ser comparada com a chave de classificação de um elemento do multimap que está sendo pesquisado.

Valor de retorno

Um iterador ou const_iterator que trata a localização de um elemento em uma multimap com uma chave, que é igual ou maior que a chave de argumento ou que trata o local após o último elemento na multimap se nenhuma correspondência for encontrada para a chave.

Se o valor retornado de lower_bound for atribuído a um const_iterator, o objeto multimap não poderá ser modificado. Se o valor retornado de lower_bound for atribuído a um iterador, o objeto multimap pode ser modificado.

Exemplo

// multimap_lower_bound.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;
   multimap <int, int> :: const_iterator m1_AcIter, m1_RcIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );

   m1_RcIter = m1.lower_bound( 2 );
   cout << "The element of multimap m1 with a key of 2 is: "
        << m1_RcIter -> second << "." << endl;

   m1_RcIter = m1.lower_bound( 3 );
   cout << "The first element of multimap m1 with a key of 3 is: "
        << m1_RcIter -> second << "." << endl;

   // If no match is found for the key, end( ) is returned
   m1_RcIter = m1.lower_bound( 4 );

   if ( m1_RcIter == m1.end( ) )
      cout << "The multimap m1 doesn't have an element "
              << "with a key of 4." << endl;
   else
      cout << "The element of multimap m1 with a key of 4 is: "
                << m1_RcIter -> second << "." << endl;

   // The element at a specific location in the multimap can be
   // found using a dereferenced iterator addressing the location
   m1_AcIter = m1.end( );
   m1_AcIter--;
   m1_RcIter = m1.lower_bound( m1_AcIter -> first );
   cout << "The first element of m1 with a key matching\n"
        << "that of the last element is: "
        << m1_RcIter -> second << "." << endl;

   // Note that the first element with a key equal to
   // the key of the last element is not the last element
   if ( m1_RcIter == --m1.end( ) )
      cout << "This is the last element of multimap m1."
           << endl;
   else
      cout << "This is not the last element of multimap m1."
           << endl;
}
The element of multimap m1 with a key of 2 is: 20.
The first element of multimap m1 with a key of 3 is: 20.
The multimap m1 doesn't have an element with a key of 4.
The first element of m1 with a key matching
that of the last element is: 20.
This is not the last element of multimap m1.

multimap::mapped_type

Um tipo que representa o tipo de dados armazenado em um multimap.

typedef Type mapped_type;

Comentários

mapped_type é um sinônimo do parâmetro de modelo Type.

Para obter mais informações sobre Type, confira o tópico multimap Classe.

Exemplo

Veja o exemplo de value_type que demonstra como declarar e usar key_type.

multimap::max_size

Retorna o comprimento máximo do multimap.

size_type max_size() const;

Valor de retorno

O comprimento máximo possível da multimap.

Exemplo

// multimap_max_size.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;
   multimap <int, int> :: size_type i;

   i = m1.max_size( );
   cout << "The maximum possible length "
        << "of the multimap is " << i << "." << endl;
}

multimap::multimap

Constrói um multimap que está vazio ou que é uma cópia de todo ou parte de algum outro multimap.

multimap();

explicit multimap(
    const Traits& Comp);

multimap(
    const Traits& Comp,
    const Allocator& Al);

map(
    const multimap& Right);

multimap(
    multimap&& Right);

multimap(
    initializer_list<value_type> IList);

multimap(
    initializer_list<value_type> IList,
    const Compare& Comp);

multimap(
    initializer_list<value_type> IList,
    const Compare& Comp,
    const Allocator& Al);

template <class InputIterator>
multimap(
    InputIterator First,
    InputIterator Last);

template <class InputIterator>
multimap(
    InputIterator First,
    InputIterator Last,
    const Traits& Comp);

template <class InputIterator>
multimap(
    InputIterator First,
    InputIterator Last,
    const Traits& Comp,
    const Allocator& Al);

Parâmetros

Al
A classe do alocador de armazenamento a ser usado neste objeto multimap, cujo padrão é Allocator.

Comp
A função de comparação do tipo constTraits usada para ordenar os elementos no mapa, cujo padrão é Traits.

Right
O mapa do qual o conjunto criado é uma cópia.

First
A posição do primeiro elemento no intervalo de elementos a serem copiados.

Last
A posição do primeiro elemento além do intervalo de elementos a serem copiados.

IList
O initializer_list do qual copiar os elementos.

Comentários

Todos os construtores armazenam um tipo de objeto de alocador que gerencia o armazenamento de memória para multimap e que, posteriormente, pode ser retornado ao chamar get_allocator. O parâmetro do alocador muitas vezes é omitido nas declarações de classe e nas macros de pré-processamento usadas para substituir os alocadores alternativos.

Todos os construtores inicializam seu multimap.

Todos os construtores armazenam um objeto de função do tipo Traits, que é usado para estabelecer uma ordem entre as chaves da multimap e que posteriormente pode ser retornado ao chamar key_comp.

Os primeiros três construtores especificam um multimap inicial vazio, com o segundo especificando o tipo de função de comparação (Comp) a ser usada para estabelecer a ordem dos elementos e a terceira especificando explicitamente o tipo de alocador (Al) a ser usado. A palavra-chave explicit suprime determinados tipos de conversão do tipo automático.

O quarto construtor especifica uma cópia do multimap Right.

O quinto construtor especifica uma cópia de multimap movendo para Direita.

Os construtores 6º, 7º e 8º copiam os membros de um initializer_list.

Os próximos três construtores copiam o intervalo [First, Last) de um mapa com clareza crescente para especificar o tipo de função de comparação da classe Traits e do alocador.

Exemplo

// multimap_ctor.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main()
{
    using namespace std;
    typedef pair <int, int> Int_Pair;

    // Create an empty multimap m0 of key type integer
    multimap <int, int> m0;

    // Create an empty multimap m1 with the key comparison
    // function of less than, then insert 4 elements
    multimap <int, int, less<int> > m1;
    m1.insert(Int_Pair(1, 10));
    m1.insert(Int_Pair(2, 20));
    m1.insert(Int_Pair(3, 30));
    m1.insert(Int_Pair(4, 40));

    // Create an empty multimap m2 with the key comparison
    // function of greater than, then insert 2 elements
    multimap <int, int, less<int> > m2;
    m2.insert(Int_Pair(1, 10));
    m2.insert(Int_Pair(2, 20));

    // Create a multimap m3 with the
    // allocator of multimap m1
    multimap <int, int>::allocator_type m1_Alloc;
    m1_Alloc = m1.get_allocator();
    multimap <int, int> m3(less<int>(), m1_Alloc);
    m3.insert(Int_Pair(3, 30));

    // Create a copy, multimap m4, of multimap m1
    multimap <int, int> m4(m1);

    // Create a multimap m5 by copying the range m1[ first,  last)
    multimap <int, int>::const_iterator m1_bcIter, m1_ecIter;
    m1_bcIter = m1.begin();
    m1_ecIter = m1.begin();
    m1_ecIter++;
    m1_ecIter++;
    multimap <int, int> m5(m1_bcIter, m1_ecIter);

    // Create a multimap m6 by copying the range m4[ first,  last)
    // and with the allocator of multimap m2
    multimap <int, int>::allocator_type m2_Alloc;
    m2_Alloc = m2.get_allocator();
    multimap <int, int> m6(m4.begin(), ++m4.begin(), less<int>(), m2_Alloc);

    cout << "m1 =";
    for (auto i : m1)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    cout << "m2 =";
    for (auto i : m2)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    cout << "m3 =";
    for (auto i : m3)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    cout << "m4 =";
    for (auto i : m4)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    cout << "m5 =";
    for (auto i : m5)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    cout << "m6 =";
    for (auto i : m6)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    // Create a multimap m8 by copying in an initializer_list
    multimap<int, int> m8{ { { 1, 1 }, { 2, 2 }, { 3, 3 }, { 4, 4 } } };
    cout << "m8: = ";
    for (auto i : m8)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    // Create a multimap m9 with an initializer_list and a comparator
    multimap<int, int> m9({ { 5, 5 }, { 6, 6 }, { 7, 7 }, { 8, 8 } }, less<int>());
    cout << "m9: = ";
    for (auto i : m9)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    // Create a multimap m10 with an initializer_list, a comparator, and an allocator
    multimap<int, int> m10({ { 9, 9 }, { 10, 10 }, { 11, 11 }, { 12, 12 } }, less<int>(), m9.get_allocator());
    cout << "m10: = ";
    for (auto i : m10)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

}

multimap::operator=

Substitui os elementos de um multimap por uma cópia de outro multimap.

multimap& operator=(const multimap& right);

multimap& operator=(multimap&& right);

Parâmetros

right
O multimap que está sendo copiado no multimap.

Comentários

Após apagar os elementos existentes em um multimap, operator= copiará ou moverá o conteúdo de right para multimap.

Exemplo

// multimap_operator_as.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
   {
   using namespace std;
   multimap<int, int> v1, v2, v3;
   multimap<int, int>::iterator iter;

   v1.insert(pair<int, int>(1, 10));

   cout << "v1 = " ;
   for (iter = v1.begin(); iter != v1.end(); iter++)
      cout << iter->second << " ";
   cout << endl;

   v2 = v1;
   cout << "v2 = ";
   for (iter = v2.begin(); iter != v2.end(); iter++)
      cout << iter->second << " ";
   cout << endl;

// move v1 into v2
   v2.clear();
   v2 = move(v1);
   cout << "v2 = ";
   for (iter = v2.begin(); iter != v2.end(); iter++)
      cout << iter->second << " ";
   cout << endl;
   }

multimap::pointer

Um tipo que fornece um ponteiro para um elemento em um multimap.

typedef typename allocator_type::pointer pointer;

Comentários

Um tipo de pointer pode ser usado para modificar o valor de um elemento.

Na maioria dos casos, um iterator deve ser usado para acessar os elementos em um objeto multimap.

multimap::rbegin

Retorna um iterador que trata o primeiro elemento em um multimap invertido.

const_reverse_iterator rbegin() const;

reverse_iterator rbegin();

Valor de retorno

Um iterador bidirecional constante invertido que aborda o primeiro elemento em uma multimap invertida ou abordando o que foi o último elemento na multimap não invertida.

Comentários

rbegin é usado com um multimap invertido, assim como begin é usado com um multimap.

Se o valor retornado de rbegin for atribuído a uma const_reverse_iterator, o objeto multimap não poderá ser modificado. Se o valor retornado de rbegin for atribuído a uma reverse_iterator, o objeto multimap não poderá ser modificado.

rbegin pode ser usado para iterar em um multimap no sentido inverso.

Exemplo

// multimap_rbegin.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;

   multimap <int, int> :: iterator m1_Iter;
   multimap <int, int> :: reverse_iterator m1_rIter;
   multimap <int, int> :: const_reverse_iterator m1_crIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );

   m1_rIter = m1.rbegin( );
   cout << "The first element of the reversed multimap m1 is "
        << m1_rIter -> first << "." << endl;

   // begin can be used to start an iteration
   // through a multimap in a forward order
   cout << "The multimap is: ";
   for ( m1_Iter = m1.begin( ) ; m1_Iter != m1.end( ); m1_Iter++)
      cout << m1_Iter -> first << " ";
      cout << "." << endl;

   // rbegin can be used to start an iteration
   // through a multimap in a reverse order
   cout << "The reversed multimap is: ";
   for ( m1_rIter = m1.rbegin( ) ; m1_rIter != m1.rend( ); m1_rIter++)
      cout << m1_rIter -> first << " ";
      cout << "." << endl;

   // A multimap element can be erased by dereferencing its key
   m1_rIter = m1.rbegin( );
   m1.erase ( m1_rIter -> first );

   m1_rIter = m1.rbegin( );
   cout << "After the erasure, the first element "
        << "in the reversed multimap is "
        << m1_rIter -> first << "." << endl;
}
The first element of the reversed multimap m1 is 3.
The multimap is: 1 2 3 .
The reversed multimap is: 3 2 1 .
After the erasure, the first element in the reversed multimap is 2.

multimap::reference

Um tipo que fornece uma referência a um elemento armazenado em um multimap.

typedef typename allocator_type::reference reference;

Exemplo

// multimap_ref.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );

   // Declare and initialize a const_reference &Ref1
   // to the key of the first element
   const int &Ref1 = ( m1.begin( ) -> first );

   // The following line would cause an error because the
   // non-const_reference can't be used to access the key
   // int &Ref1 = ( m1.begin( ) -> first );

   cout << "The key of first element in the multimap is "
        << Ref1 << "." << endl;

   // Declare and initialize a reference &Ref2
   // to the data value of the first element
   int &Ref2 = ( m1.begin( ) -> second );

   cout << "The data value of first element in the multimap is "
        << Ref2 << "." << endl;

   // The non-const_reference can be used to modify the
   // data value of the first element
   Ref2 = Ref2 + 5;
   cout << "The modified data value of first element is "
        << Ref2 << "." << endl;
}
The key of first element in the multimap is 1.
The data value of first element in the multimap is 10.
The modified data value of first element is 15.

multimap::rend

Retorna um iterador que trata o local após o último elemento em um multimap invertido.

const_reverse_iterator rend() const;

reverse_iterator rend();

Valor de retorno

Um iterador bidirecional inverso que aborda a localização que vem após o último elemento em uma multimap invertida (o local que precedeu o primeiro elemento no multimap não invertido).

Comentários

rend é usado com um multimap invertido, assim como end é usado com um multimap.

Se o valor retornado de rend for atribuído a uma const_reverse_iterator, o objeto multimap não poderá ser modificado. Se o valor retornado de rend for atribuído a uma reverse_iterator, o objeto multimap não poderá ser modificado.

rend pode ser usado para testar se um iterador inverso chegou ao final de seu multimap.

O valor retornado por rend não deve ser desreferenciado.

Exemplo

// multimap_rend.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;

   multimap <int, int> :: iterator m1_Iter;
   multimap <int, int> :: reverse_iterator m1_rIter;
   multimap <int, int> :: const_reverse_iterator m1_crIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );

   m1_rIter = m1.rend( );
   m1_rIter--;
   cout << "The last element of the reversed multimap m1 is "
        << m1_rIter -> first << "." << endl;

   // begin can be used to start an iteration
   // through a multimap in a forward order
   cout << "The multimap is: ";
   for ( m1_Iter = m1.begin( ) ; m1_Iter != m1.end( ); m1_Iter++)
      cout << m1_Iter -> first << " ";
      cout << "." << endl;

   // rbegin can be used to start an iteration
   // through a multimap in a reverse order
   cout << "The reversed multimap is: ";
   for ( m1_rIter = m1.rbegin( ) ; m1_rIter != m1.rend( ); m1_rIter++)
      cout << m1_rIter -> first << " ";
      cout << "." << endl;

   // A multimap element can be erased by dereferencing to its key
   m1_rIter = --m1.rend( );
   m1.erase ( m1_rIter -> first );

   m1_rIter = m1.rend( );
   m1_rIter--;
   cout << "After the erasure, the last element "
        << "in the reversed multimap is "
        << m1_rIter -> first << "." << endl;
}
The last element of the reversed multimap m1 is 1.
The multimap is: 1 2 3 .
The reversed multimap is: 3 2 1 .
After the erasure, the last element in the reversed multimap is 2.

multimap::reverse_iterator

Um tipo que fornece um iterador bidirecional que pode ler ou modificar um elemento em um multimap invertido.

typedef std::reverse_iterator<iterator> reverse_iterator;

Comentários

Um tipo reverse_iterator é usado para iterar a multimap em ordem inversa.

O reverse_iterator definido por pontos multimap a objetos de value_type, que são do tipo pair<const Key, Type>. O valor da chave está disponível por meio do primeiro par de membros e o valor do elemento mapeado está disponível por meio do segundo membro do par.

Para desreferenciar um reverse_iterator rIter apontamento para um elemento em um multimap, use o -> operador.

Para acessar o valor de chave do elemento, use rIter->first, que é equivalente a (*rIter).first. Para acessar o valor dos dados mapeados do elemento, use rIter->second, que é equivalente a (*rIter).second.

Exemplo

Veja o exemplo de rbegin que demonstra como declarar e usar reverse_iterator.

multimap::size

Retorna o número de elementos no multimap.

size_type size() const;

Valor de retorno

O comprimento atual do multimap.

Exemplo

O exemplo a seguir demonstra o uso da função de membro multimap::size.

// multimap_size.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main()
{
    using namespace std;
    multimap<int, int> m1, m2;
    multimap<int, int>::size_type i;
    typedef pair<int, int> Int_Pair;

    m1.insert(Int_Pair(1, 1));
    i = m1.size();
    cout << "The multimap length is " << i << "." << endl;

    m1.insert(Int_Pair(2, 4));
    i = m1.size();
    cout << "The multimap length is now " << i << "." << endl;
}
The multimap length is 1.
The multimap length is now 2.

multimap::size_type

Um tipo inteiro sem sinal que conta o número de elementos em um multimap.

typedef typename allocator_type::size_type size_type;

Exemplo

Veja o exemplo de size que demonstra como declarar e usar size_type

multimap::swap

Troca os elementos de dois multimaps.

void swap(
    multimap<Key, Type, Traits, Allocator>& right);

Parâmetros

right
O multimap fornecimento dos elementos a serem trocados, ou os multimap elementos de quem devem ser trocados com os multimap leftdo .

Comentários

A função membro não invalida nenhuma referência, ponteiro ou iterador que designa elementos nos dois multimaps cujos elementos estão sendo trocados.

Exemplo

// multimap_swap.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1, m2, m3;
   multimap <int, int>::iterator m1_Iter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );
   m2.insert ( Int_Pair ( 10, 100 ) );
   m2.insert ( Int_Pair ( 20, 200 ) );
   m3.insert ( Int_Pair ( 30, 300 ) );

   cout << "The original multimap m1 is:";
   for ( m1_Iter = m1.begin( ); m1_Iter != m1.end( ); m1_Iter++ )
      cout << " " << m1_Iter -> second;
   cout   << "." << endl;

   // This is the member function version of swap
   m1.swap( m2 );

   cout << "After swapping with m2, multimap m1 is:";
   for ( m1_Iter = m1.begin( ); m1_Iter != m1.end( ); m1_Iter++ )
      cout << " " << m1_Iter -> second;
   cout  << "." << endl;

   // This is the specialized template version of swap
   swap( m1, m3 );

   cout << "After swapping with m3, multimap m1 is:";
   for ( m1_Iter = m1.begin( ); m1_Iter != m1.end( ); m1_Iter++ )
      cout << " " << m1_Iter -> second;
   cout   << "." << endl;
}
The original multimap m1 is: 10 20 30.
After swapping with m2, multimap m1 is: 100 200.
After swapping with m3, multimap m1 is: 300.

multimap::upper_bound

Retorna um iterator para o primeiro elemento em um multimap com uma chave que é maior que uma chave especificada.

iterator upper_bound(const Key& key);

const_iterator upper_bound(const Key& key) const;

Parâmetros

key
A chave do argumento a ser comparada com a chave de classificação de um elemento do multimap que está sendo pesquisado.

Valor de retorno

Um iterator ou const_iterator que tratará a localização de um elemento em um multimap com uma chave, que é maior que a chave de argumento ou que tratará o local após o último elemento no multimap se nenhuma correspondência for encontrada para a chave.

Se o valor retornado for atribuído a um const_iterator, o objeto multimap não pode ser modificado. Se o valor retornado for atribuído a um iterator, o objeto multimap não pode ser modificado.

Exemplo

// multimap_upper_bound.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;
   multimap <int, int> :: const_iterator m1_AcIter, m1_RcIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );
   m1.insert ( Int_Pair ( 3, 40 ) );

   m1_RcIter = m1.upper_bound( 1 );
   cout << "The 1st element of multimap m1 with "
        << "a key greater than 1 is: "
        << m1_RcIter -> second << "." << endl;

   m1_RcIter = m1.upper_bound( 2 );
   cout << "The first element of multimap m1 with a key "
        << " greater than 2 is: "
        << m1_RcIter -> second << "." << endl;

   // If no match is found for the key, end( ) is returned
   m1_RcIter = m1.lower_bound( 4 );

   if ( m1_RcIter == m1.end( ) )
      cout << "The multimap m1 doesn't have an element "
           << "with a key of 4." << endl;
   else
      cout << "The element of multimap m1 with a key of 4 is: "
           << m1_RcIter -> second << "." << endl;

   // The element at a specific location in the multimap can be
   // found using a dereferenced iterator addressing the location
   m1_AcIter = m1.begin( );
   m1_RcIter = m1.upper_bound( m1_AcIter -> first );
   cout << "The first element of m1 with a key greater than\n"
        << "that of the initial element of m1 is: "
        << m1_RcIter -> second << "." << endl;
}
The 1st element of multimap m1 with a key greater than 1 is: 20.
The first element of multimap m1 with a key  greater than 2 is: 30.
The multimap m1 doesn't have an element with a key of 4.
The first element of m1 with a key greater than
that of the initial element of m1 is: 20.

multimap::value_comp

A função membro retorna um objeto de função que determina a ordem dos elementos em um multimap comparando os respectivos valores de chave.

value_compare value_comp() const;

Valor de retorno

Retorna o objeto da função de comparação que um multimap usa para ordenar os seus elementos.

Comentários

Para um multimap m, se dois elementos e1(k1, d1) e e2(k2, d2) são objetos do tipo value_type, onde k1 e k2 são suas chaves do tipo key_type e d1 e d2 são seus dados do tipo mapped_type, então m.value_comp(e1, e2) é equivalente a m.key_comp(k1, k2).

Exemplo

// multimap_value_comp.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;

   multimap <int, int, less<int> > m1;
   multimap <int, int, less<int> >::value_compare vc1 = m1.value_comp( );
   multimap<int,int>::iterator Iter1, Iter2;

   Iter1= m1.insert ( multimap <int, int> :: value_type ( 1, 10 ) );
   Iter2= m1.insert ( multimap <int, int> :: value_type ( 2, 5 ) );

   if( vc1( *Iter1, *Iter2 ) == true )
   {
      cout << "The element ( 1,10 ) precedes the element ( 2,5 )."
           << endl;
   }
   else
   {
      cout << "The element ( 1,10 ) does "
           << "not precede the element ( 2,5 )."
           << endl;
   }

   if( vc1( *Iter2, *Iter1 ) == true )
   {
      cout << "The element ( 2,5 ) precedes the element ( 1,10 )."
           << endl;
   }
   else
   {
      cout << "The element ( 2,5 ) does "
           << "not precede the element ( 1,10 )."
           << endl;
   }
}
The element ( 1,10 ) precedes the element ( 2,5 ).
The element ( 2,5 ) does not precede the element ( 1,10 ).

multimap::value_type

Um tipo que representa o tipo de objeto armazenado como um elemento em um mapa.

typedef pair<const Key, Type> value_type;

Exemplo

// multimap_value_type.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   typedef pair <const int, int> cInt2Int;
   multimap <int, int> m1;
   multimap <int, int> :: key_type key1;
   multimap <int, int> :: mapped_type mapped1;
   multimap <int, int> :: value_type value1;
   multimap <int, int> :: iterator pIter;

   // value_type can be used to pass the correct type
   // explicitly to avoid implicit type conversion
   m1.insert ( multimap <int, int> :: value_type ( 1, 10 ) );

   // Compare another way to insert objects into a hash_multimap
   m1.insert ( cInt2Int ( 2, 20 ) );

   // Initializing key1 and mapped1
   key1 = ( m1.begin( ) -> first );
   mapped1 = ( m1.begin( ) -> second );

   cout << "The key of first element in the multimap is "
        << key1 << "." << endl;

   cout << "The data value of first element in the multimap is "
        << mapped1 << "." << endl;

   // The following line would cause an error because
   // the value_type is not assignable
   // value1 = cInt2Int ( 4, 40 );

   cout  << "The keys of the mapped elements are:";
   for ( pIter = m1.begin( ) ; pIter != m1.end( ) ; pIter++ )
      cout << " " << pIter -> first;
   cout << "." << endl;

   cout  << "The values of the mapped elements are:";
   for ( pIter = m1.begin( ) ; pIter != m1.end( ) ; pIter++ )
      cout << " " << pIter -> second;
   cout << "." << endl;
}
The key of first element in the multimap is 1.
The data value of first element in the multimap is 10.
The keys of the mapped elements are: 1 2.
The values of the mapped elements are: 10 20.

Confira também

Contêineres
Acesso Thread-Safe na Biblioteca Padrão C++
Referência da biblioteca padrão C++