Classe `map`

Artigo
06/16/2023

Usado 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 é exclusivo e usado para classificar os dados automaticamente.

O valor de um elemento em um mapa pode ser alterado diretamente. O valor de chave é uma constante e não pode ser alterado. Em vez disso, os valores de chave associados aos elementos antigos devem ser excluídos e os novos valores de chave devem ser inseridos para novos elementos.

Sintaxe

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

Parâmetros

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

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

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 map. Esse argumento é opcional e 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<>, que não tem nenhum parâmetro de tipo. Confira Pesquisa Heterogênea em Contêineres Associativos para saber mais.

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 map da Biblioteca Padrão C++ é:

Um contêiner de tamanho variável que recupera com eficiência valores de elemento com base em valores de chave associados.
Reversível, pois fornece iteradores bidirecionais para acessar seus elementos.
Classificada, pois seus elementos são ordenados por valores de chave, de acordo com uma função de comparação especificada.
Exclusivo. porque cada um de seus elementos deve ter uma chave exclusiva.
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 independente do tipo de chave ou elemento. Os tipos de dados 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 map é um iterador bidirecional, mas as funções de membro das classes inserte map têm versões que usam um iterador de entrada mais fraco como parâmetros de modelo, com menos requisitos de funcionalidade do que aqueles garantidos pela classe de iteradores bidirecionais. Os conceitos de iterador diferente são relacionados por refinamentos em sua funcionalidade. Cada conceito de iterador tem seu próprio conjunto de requisitos e os algoritmos que funcionam com ele devem ser limitados por esses requisitos. Um iterador de entrada pode ser desreferenciado para fazer referência a algum objeto e pode se incrementado para o próximo iterador na sequência.

É recomendável basear a escolha do tipo de contêiner no tipo de pesquisa e inserção que é exigido pelo aplicativo. Os contêineres associativos são otimizados para as operações de pesquisa, inserção e remoção. As funções de membro que oferecem suporte explicitamente a essas operações as executam no pior caso, proporcional ao logaritmo do número de elementos no contêiner. A inserção de elementos não invalida iteradores e a remoção de elementos invalida apenas os iteradores que apontavam especificamente para os elementos removidos.

É recomendável fazer o mapa do contêiner associativo escolhido quando as condições que associam os valores às chaves forem atendidas pelo aplicativo. Um modelo para esse tipo de estrutura é uma lista ordenada de palavras-chave que ocorrem uma única vez e que tenham valores de cadeia de caracteres associados que forneçam definições. Se uma palavra tiver mais de uma definição correta, essa chave não será exclusiva, de modo que um multimapa seria um contêiner melhor. Se apenas a lista de palavras estiver sendo armazenada, um conjunto será o contêiner apropriado. Se forem permitidas várias ocorrências das palavras, um multiset será mais adequado.

O mapa ordena os elementos que controla chamando um objeto de função armazenado do tipo key_compare. Esse objeto armazenado é uma função de comparação que é acessada chamando o método key_comp. De modo geral, dois elementos determinados são comparados para saber se um é menor que o outro ou se são equivalentes. Como todos os elementos são comparados, é criada uma sequência ordenada de elementos não equivalentes.

Observação

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 tem 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, na qual dois objetos x e y serão definidos como equivalentes quando ambos, f(x,y) e f(y,x) forem 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

Nome	Descrição
`map`	Constrói uma lista de um tamanho específico, ou com elementos de um valor específico, ou com um `allocator` específico, ou como uma cópia de algum outro mapa.

Typedefs

Nome	Descrição
`allocator_type`	Um typedef para a classe `allocator` do mapa.
`const_iterator`	Um typedef para um iterador bidirecional que pode ler um elemento `const` no `map`.
`const_pointer`	Um typedef de um ponteiro para um elemento `const` em um mapa.
`const_reference`	Um typedef de uma referência para um elemento `const` armazenado em um mapa 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 `map`.
`difference_type`	Um typedef de inteiro com sinal para o número de elementos de um mapa em um intervalo entre os elementos apontado pelos iteradores.
`iterator`	Um typedef para um iterador bidirecional que pode ler ou modificar qualquer elemento em um mapa.
`key_compare`	Um typedef de um objeto de função que pode comparar duas chaves de classificação para determinar a ordem relativa de dois elementos no `map`.
`key_type`	Um typedef para a chave de classificação armazenada em cada elemento do mapa.
`mapped_type`	Um typedef para os dados armazenados em cada elemento de um mapa.
`pointer`	Um typedef de um ponteiro para um elemento `const` em um mapa.
`reference`	Um typedef de uma referência para um elemento armazenado em um mapa.
`reverse_iterator`	Um typedef para um iterador bidirecional que pode ler ou modificar um elemento em um mapa invertido.
`size_type`	Um typedef de inteiro não assinado para o número de elementos em um mapa
`value_type`	Um typedef para o tipo de objeto armazenado como um elemento em um mapa.

Funções de membro

Função de membro	Descrição
`at`	Localiza um elemento com o valor da chave especificada.
`begin`	Retorna um iterador que aponta para o primeiro elemento no `map`.
`cbegin`	Retorna um iterador const que aponta para o primeiro elemento no `map`.
`cend`	Retorna um iterador const que ultrapassa o fim.
`clear`	Apaga todos os elementos de um `map`.
`contains`^C++20	Verifique se há um elemento com a chave especificada no `map`.
`count`	Retorna o número de elementos em um mapa cuja chave corresponde à chave especificada em um parâmetro.
`crbegin`	Retorna um iterador const que aponta para o primeiro elemento em um `map` invertido.
`crend`	Retorna um iterador const que aponta para o local após o último elemento em um `map` invertido.
`emplace`	Insere um elemento construído adequadamente em um `map`.
`emplace_hint`	Insere um elemento construído adequadamente no `map`, com uma dica de posicionamento.
`empty`	Retornará `true`, se um `map` estiver vazio.
`end`	Retorna o iterador que ultrapassa o fim.
`equal_range`	Retorna um par de iteradores. O primeiro iterador no par aponta para o primeiro elemento em um `map` com uma chave que é maior que uma chave especificada. O segundo iterador no par aponta para o primeiro elemento no `map` com uma chave que é igual ou maior que a chave.
`erase`	Remove das posições especificadas um elemento ou um intervalo de elementos em uma mapa.
`find`	Retorna um iterador que aponta para o local de um elemento em um `map` que tem uma chave igual a uma chave especificada.
`get_allocator`	Retorna uma cópia do objeto `allocator` que é usada para construir o `map`.
`insert`	Insere um elemento ou um intervalo de elementos no `map` na posição especificada.
`key_comp`	Retorna uma cópia do objeto de comparação que é usada para ordenar chaves em um `map`.
`lower_bound`	Retorna um iterador para o primeiro elemento em um `map` que tem um valor de chave que é igual ou maior que uma chave especificada.
`max_size`	Retorna o comprimento máximo do `map`.
`rbegin`	Retorna um iterador que aponta para o primeiro elemento em um `map` invertido.
`rend`	Retorna um iterador que aponta para o local após o último elemento em um `map` invertido.
`size`	Retorna o número de elementos no `map`.
`swap`	Troca os elementos de dois mapas.
`upper_bound`	Retorna um iterador para o primeiro elemento em um `map` que tem um valor de chave que é maior que uma chave especificada.
`value_comp`	Recupera uma cópia do objeto de comparação que é usada para ordenar valores de elemento em um `map`.

Operadores

Nome	Descrição
`operator[]`	Insere um elemento em um mapa com um valor de chave especificado.
`operator=`	Substitui os elementos de um mapa por uma cópia de outro mapa.

`allocator_type`

Um tipo que representa a classe allocator do objeto de mapa.

typedef Allocator allocator_type;

Exemplo

Confira get_allocator, para ver um exemplo de uso de allocator_type.

`at`

Localiza um elemento com um valor de chave especificado.

Type& at(const Key& key);

const Type& at(const Key& key) const;

Parâmetros

key
O valor de chave a ser localizado.

Valor de Devolução

Uma referência ao valor de dados do elemento encontrado.

Comentários

Se o valor da chave do argumento não for encontrado, a função lançará um objeto da classe out_of_range Classe.

Exemplo

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

typedef std::map<char, int> Mymap;
int main()
    {
    Mymap c1;

    c1.insert(Mymap::value_type('a', 1));
    c1.insert(Mymap::value_type('b', 2));
    c1.insert(Mymap::value_type('c', 3));

// find and show elements
    std::cout << "c1.at('a') == " << c1.at('a') << std::endl;
    std::cout << "c1.at('b') == " << c1.at('b') << std::endl;
    std::cout << "c1.at('c') == " << c1.at('c') << std::endl;

    return (0);
    }

`begin`

Retorna um iterador que trata o primeiro elemento no map.

const_iterator begin() const;

iterator begin();

Valor de Devolução

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

Exemplo

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

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

   map <int, int> :: iterator m1_Iter;
   map <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 because the iterator is const
   // m1_cIter = m1.begin ( );
   // m1.erase ( m1_cIter );

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

The first element of m1 is 0
The first element of m1 is now 1

`cbegin`

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

const_iterator cbegin() const;

Valor de Devolução

Um iterador bidirecional const que trata 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

`cend`

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

const_iterator cend() const;

Valor de Devolução

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.

`clear`

Apaga todos os elementos de um mapa.

void clear();

Exemplo

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

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

int main()
{
    using namespace std;
    map<int, int> m1;
    map<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 map is initially "
         << i << "." << endl;

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

The size of the map is initially 2.
The size of the map after clearing is 0.

`const_iterator`

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

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 pelo mapa aponta para elementos que são objetos de value_type, que são do tipo pair<constKey, Type>, cujo primeiro membro é a chave para o elemento e o segundo membro é a referência mapeada mantida pelo elemento.

Para desreferenciar um const_iteratorcIter que aponta para um elemento em um mapa, 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

Confira begin, para ver um exemplo de uso de const_iterator.

`const_pointer`

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

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 de mapa.

`const_reference`

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

typedef typename allocator_type::const_reference const_reference;

Exemplo

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

int main( )
{
   using namespace std;
   map <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 as 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 map 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 map is "
        << Ref2 << "." << endl;
}

The key of first element in the map is 1.
The data value of first element in the map is 10.

`const_reverse_iterator`

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

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 mapa invertido.

O const_reverse_iterator definido pelo mapa aponta para elementos que são objetos de value_type, que são do tipo pair<const Key, Type>, cujo primeiro membro é a chave para o elemento e o segundo membro é a referência mapeada mantida pelo elemento.

Para desreferenciar um const_reverse_iterator crIter que aponta para um elemento em um mapa, 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.

`count`

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

size_type count(const Key& key) const;

Parâmetros

key
O valor de chave dos elementos a serem correspondidos do mapa.

Valor de Devolução

1, se o mapa tiver um elemento cuja chave de classificação corresponde à chave de parâmetro; 0, se o mapa não tiver um elemento com uma chave correspondente.

Comentários

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

[ lower_bound(key), upper_bound(key) )

que será 0 ou 1, no caso do mapa, que é um contêiner associativo exclusivo.

Exemplo

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

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

int main()
{
    using namespace std;
    map<int, int> m1;
    map<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));

    // Keys must be unique in map, so duplicates are ignored
    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: 1.
The number of elements in m1 with a sort key of 2 is: 1.
The number of elements in m1 with a sort key of 3 is: 0.

`contains`

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

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 Devolução

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::map<int, bool> m = {{0, true},{1, false}};

    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::map<std::string, int, std::less<>> m2 = {{"ten", 10}, {"twenty", 20}, {"thirty", 30}};
    std::cout << m2.contains("ten");

    return 0;
}

true
false
true

`crbegin`

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

const_reverse_iterator crbegin() const;

Valor de Devolução

Um iterador bidirecional constante invertido que aborda o primeiro elemento em um map invertido ou abordando o que foi o último elemento no map não invertido.

Comentários

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

Com o valor de retorno crbegin, o objeto map não pode ser modificado

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

Exemplo

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

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

   map <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 map m1 is "
        << m1_crIter -> first << "." << endl;
}

The first element of the reversed map m1 is 3.

`crend`

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

const_reverse_iterator crend() const;

Valor de Devolução

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

Comentários

crend é usado com um mapa invertido, assim como end é usado com um map.

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

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

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

Exemplo

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

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

   map <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 map m1 is "
        << m1_crIter -> first << "." << endl;
}

The last element of the reversed map m1 is 1.

`difference_type`

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

typedef allocator_type::difference_type difference_type;

Comentários

difference_type é o tipo retornado ao subtrair ou incrementar por meio de iteradores do contêiner. O 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

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

int main( )
{
   using namespace std;
   map <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 ) );
   m1.insert ( Int_Pair ( 2, 30 ) );

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

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

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

The number of elements in the map m1 is: 4.

`emplace`

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

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

Parâmetros

args
Os argumentos encaminhados para construir um elemento para inserir no mapa, a menos que já contenha um elemento cujo valor seja ordenado de forma equivalente.

Valor de Devolução

Um pair cujo componente bool será true se for feita uma inserção, e false se o mapa já contiver um elemento de valor equivalente na ordenação. O componente do iterador do par de valores retornados apontará para o elemento recém-inserido, se o componente bool for verdadeiro, ou para o elemento existente, se o componente bool for falso.

Para acessar o componente do iterador de um pairpr, use pr.first, para desreferenciá-lo, use *pr.first. Para acessar o componente bool, use pr.second. Para obter um exemplo, consulte o código de amostra mais adiante neste artigo.

Comentários

Nenhum iterador ou referência será invalidada por essa função.

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.

Exemplo

// map_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: ";

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

    cout << endl;
}

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

    auto ret = m1.emplace(10, "ten");

    if (!ret.second){
        auto pr = *ret.first;
        cout << "Emplace failed, element with key 10 already exists."
            << endl << "  The existing element is (" << pr.first << ", " << pr.second << ")"
            << endl;
        cout << "map not modified" << endl;
    }
    else{
        cout << "map modified, now contains ";
        print(m1);
    }
    cout << endl;

    ret = m1.emplace(10, "one zero");

    if (!ret.second){
        auto pr = *ret.first;
        cout << "Emplace failed, element with key 10 already exists."
            << endl << "  The existing element is (" << pr.first << ", " << pr.second << ")"
            << endl;
    }
    else{
        cout << "map modified, now contains ";
        print(m1);
    }
    cout << endl;
}

`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 no mapa, a menos que o mapa já contenha esse elemento ou, mais geralmente, a menos que já contenha um elemento cuja chave seja ordenada de forma equivalente.

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

Valor de Devolução

Um iterador para o elemento recém-inserido.

Se a inserção tiver falhado porque o elemento já existe, ele retornará um iterador para o elemento existente com sua chave.

Comentários

Nenhum iterador ou referência será invalidada por essa função.

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

Exemplo

// map_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()
{
    map<string, string> m1;

    // Emplace some test data
    m1.emplace("Anna", "Accounting");
    m1.emplace("Bob", "Accounting");
    m1.emplace("Carmine", "Engineering");

    cout << "map starting data: ";
    print(m1);
    cout << endl;

    // Emplace with hint
    // m1.end() should be the "next" element after this emplacement
    m1.emplace_hint(m1.end(), "Doug", "Engineering");

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

`empty`

Testa se um mapa está vazio.

bool empty() const;

Valor de Devolução

true se o mapa estiver vazio, do contrário, será false.

Exemplo

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

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

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

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

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

The map m1 is not empty.
The map m2 is empty.

`end`

Retorna o iterador que ultrapassa o fim.

const_iterator end() const;

iterator end();

Valor de Devolução

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

Comentários

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

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

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

`equal_range`

Retorna um par de iteradores que representam o lower_bound e o upper_bound da chave.

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

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

Parâmetros

key
O valor de chave do argumento a ser comparado com a chave de classificação de um elemento do mapa que está sendo pesquisado.

Valor de Devolução

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 superior, use *( pr. second).

Exemplo

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

int main( )
{
   using namespace std;
   typedef map <int, int, less<int> > IntMap;
   IntMap m1;
   map <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 <IntMap::const_iterator, IntMap::const_iterator> p1, p2;
   p1 = m1.equal_range( 2 );

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

   cout << "The upper bound of the element with "
        << "a key of 2 in the map 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 map m1 doesn't have an element "
           << "with a key less than 40." << endl;
   else
      cout << "The element of map m1 with a key >= 40 is: "
           << p2.first -> first << "." << endl;
}

The lower bound of the element with a key of 2 in the map m1 is: 20.
The upper bound of the element with a key of 2 in the map 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 map m1 doesn't have an element with a key less than 40.

`erase`

Remove um elemento ou um intervalo de elementos em um mapa 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
O valor de chave dos elementos a serem removidos.

Valor de Devolução

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 de membro, ele retorna o número de elementos que foram removidos do mapa.

Exemplo

// map_erase.cpp
// compile with: /EHsc
#include <map>
#include <string>
#include <iostream>
#include <iterator> // next() and prev() helper functions
#include <utility>  // make_pair()

using namespace std;

using mymap = map<int, string>;

void printmap(const mymap& m) {
    for (const auto& elem : m) {
        cout << " [" << elem.first << ", " << elem.second << "]";
    }
    cout << endl << "size() == " << m.size() << endl << endl;
}

int main()
{
    mymap m1;

    // Fill in some data to test with, one at a time
    m1.insert(make_pair(1, "A"));
    m1.insert(make_pair(2, "B"));
    m1.insert(make_pair(3, "C"));
    m1.insert(make_pair(4, "D"));
    m1.insert(make_pair(5, "E"));

    cout << "Starting data of map m1 is:" << endl;
    printmap(m1);
    // The 1st member function removes an element at a given position
    m1.erase(next(m1.begin()));
    cout << "After the 2nd element is deleted, the map m1 is:" << endl;
    printmap(m1);

    // Fill in some data to test with, one at a time, using an initializer list
    mymap m2
    {
        { 10, "Bob" },
        { 11, "Rob" },
        { 12, "Robert" },
        { 13, "Bert" },
        { 14, "Bobby" }
    };

    cout << "Starting data of map m2 is:" << endl;
    printmap(m2);
    // The 2nd member function removes elements
    // in the range [First, Last)
    m2.erase(next(m2.begin()), prev(m2.end()));
    cout << "After the middle elements are deleted, the map m2 is:" << endl;
    printmap(m2);

    mymap m3;

    // Fill in some data to test with, one at a time, using emplace
    m3.emplace(1, "red");
    m3.emplace(2, "yellow");
    m3.emplace(3, "blue");
    m3.emplace(4, "green");
    m3.emplace(5, "orange");
    m3.emplace(6, "purple");
    m3.emplace(7, "pink");

    cout << "Starting data of map m3 is:" << endl;
    printmap(m3);
    // The 3rd member function removes elements with a given Key
    mymap::size_type count = m3.erase(2);
    // The 3rd member function also returns the number of elements removed
    cout << "The number of elements removed from m3 is: " << count << "." << endl;
    cout << "After the element with a key of 2 is deleted, the map m3 is:" << endl;
    printmap(m3);
}

`find`

Retorna um iterador que aponta para o local de um elemento em um mapa com uma chave igual 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 mapa que está sendo pesquisado.

Valor de Devolução

Um iterador que se refere ao local de um elemento com uma chave especificada ou o local que substitui o último elemento em map (map::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 map, 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 const_iterator, o objeto de mapa não poderá ser modificado. Se o valor retornado de find for atribuído a iterator, o objeto de mapa poderá 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()
{
    map<int, string> m1({ { 40, "Zr" }, { 45, "Rh" } });
    cout << "The starting map 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 map m1 is (key, value):" << endl;
    print_collection(m1);
    cout << endl;
    findit(m1, 45);
    findit(m1, 6);
}

`get_allocator`

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

allocator_type get_allocator() const;

Valor de Devolução

O alocador usado pelo mapa.

Comentários

Os alocadores para a classe map 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

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

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

   // The following lines declare objects
   // that use the default allocator.
   map <int, int> m1;
   map <int, int, allocator<int> > m2;
   map <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\n"
        << "before free memory is exhausted: "
        << m2.max_size( ) << ".\n" << endl;

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

   // The following line creates a map m4
   // with the allocator of map 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 with the other
   if( m1_Alloc == m4_Alloc )
   {
      cout << "The allocators are interchangeable." << endl;
   }
   else
   {
      cout << "The allocators are not interchangeable." << endl;
   }
}

`insert`

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

// (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 no mapa, a menos que ele já contenha um elemento cuja chave seja ordenada de maneira equivalente.

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
Argumento da função de modelo que atende aos requisitos de um iterador de entrada 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 Devolução

As funções de membro de elemento único, (1) e (2), retornam um pair cujo componente bool será verdadeiro se uma inserção tiver sido feita e falso se o mapa já tiver um elemento cuja chave tenha um valor equivalente na ordenação. O componente do iterador do par de valores retornados apontará para o elemento recém-inserido, se o componente bool for verdadeiro, ou para o elemento existente, se o componente bool for falso.

As funções do membro de elemento único com dica, (3) e (4), retornam um iterador que aponta para a posição em que o novo elemento foi inserido no mapa ou, se um elemento com uma chave equivalente já existir, para o elemento existente.

Comentários

Nenhum iterador, ponteiro ou referência é invalidado por essa função.

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.

Para acessar o componente do iterador de um pairpr que é retornado pelas funções membro de elemento único, confira pr.first; para desreferenciar o iterador dentro do par retornado, use *pr.first, que oferece um elemento. Para acessar o componente bool, use pr.second. Para obter um exemplo, consulte o código de amostra mais adiante neste artigo.

O value_type de um contêiner é um typedef que pertence ao contêiner e para o mapa, map<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 do membro de intervalo (5) insere a sequência de valores de elemento em um mapa 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() faz referência à posição imediatamente após o último elemento no contêiner; por exemplo, a instrução m.insert(v.begin(), v.end()); tenta inserir todos os elementos de v em m. Apenas elementos com valores únicos no intervalo são inseridos; as duplicatas são ignoradas. Para observar quais elementos são rejeitados, use as versões de elemento único de insert.

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 map::emplace e map::emplace_hint.

Exemplo

// map_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
    map<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
    auto ret = m1.insert(make_pair(1, 111));
    if (!ret.second){
        auto pr = *ret.first;
        cout << "Insert failed, element with key value 1 already exists."
            << endl << "  The existing element is (" << pr.first << ", " << pr.second << ")"
            << endl;
    }
    else{
        cout << "The modified key and mapped values of m1 are:" << endl;
        print(m1);
    }
    cout << endl;

    // 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
    map<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
    map<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;

    map<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;
}

`iterator`

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

typedef implementation-defined iterator;

Comentários

O iterador definido pelos pontos do mapa para elementos que são objetos do value_type, que é do tipo pair<const Key, Type>, cujo primeiro membro é a chave para o elemento e o segundo membro é a referência mapeada mantida pelo elemento.

Para desreferenciar um iterador que aponta para um elemento em um mapa, 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.

Exemplo

Confira begin, para ver um exemplo de como declarar e usar iterator.

`key_comp`

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

key_compare key_comp() const;

Valor de Devolução

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

Comentários

O objeto armazenado define a função membro

bool operator(const Key& left, const Key& right);

que retornará true se left for precedente e não igual a right na ordem de classificação.

Exemplo

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

int main( )
{
   using namespace std;

   map <int, int, less<int> > m1;
   map <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;
   }

   map <int, int, greater<int> > m2;
   map <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.

`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 map.

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 map Classe.

Exemplo

Confira key_comp, para ver um exemplo de como declarar e usar key_compare.

`key_type`

Um tipo que descreve a chave de classificação armazenada em cada elemento do mapa.

typedef Key key_type;

Comentários

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

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

Exemplo

Confira value_type, para ver um exemplo de como declarar e usar key_type.

`lower_bound`

Retorna um iterador para o primeiro elemento em um mapa com um valor de 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
O valor de chave do argumento a ser comparado com a chave de classificação de um elemento do mapa que está sendo pesquisado.

Valor de Devolução

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

Se o valor retornado de lower_bound for atribuído a const_iterator, o objeto de mapa não poderá ser modificado. Se o valor retornado de lower_bound for atribuído a iterator, o objeto de mapa poderá ser modificado.

Exemplo

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

int main( )
{
   using namespace std;
   map <int, int> m1;
   map <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_RcIter = m1.lower_bound( 2 );
   cout << "The first element of map m1 with a key of 2 is: "
        << m1_RcIter -> second << "." << endl;

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

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

   // The element at a specific location in the map 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 element of m1 with a key matching "
        << "that of the last element is: "
        << m1_RcIter -> second << "." << endl;
}

The first element of map m1 with a key of 2 is: 20.
The map m1 doesn't have an element with a key of 4.
The element of m1 with a key matching that of the last element is: 30.

`map`

Cria um mapa que está vazio ou que é uma cópia de todo ou parte de algum outro mapa.

map();

explicit map(
    const Traits& Comp);

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

map(
    const map& Right);

map(
    map&& Right);

map(
    initializer_list<value_type> IList);

map(
    initializer_list<value_type> IList,
    const Traits& Comp);

map(
    initializer_list<value_type> IList,
    const Traits& Comp,
    const Allocator& Allocator);

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

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

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

Parâmetros

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

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

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
A initializer_list da qual os elementos a serem copiados.

Comentários

Todos os construtores armazenam um tipo de objeto de alocador que gerencia o armazenamento de memória para o mapa 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 mapa.

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

O primeiro dos três construtores especifica um mapa inicial vazio, o segundo especifica o tipo de função de comparação (Comp) a ser usada para estabelecer a ordem dos elementos e a terceira especifica 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 mapa Right.

O quinto construtor especifica uma cópia do mapa ao mover o Right.

O sexto, sétimo e oitavo construtores usam um initializer_list para copiar os membros.

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

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

int main()
{
    using namespace std;
    typedef pair <int, int> Int_Pair;
    map <int, int>::iterator m1_Iter, m3_Iter, m4_Iter, m5_Iter, m6_Iter, m7_Iter;
    map <int, int, less<int> >::iterator m2_Iter;

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

    // Create an empty map m1 with the key comparison
    // function of less than, then insert 4 elements
    map <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 map m2 with the key comparison
    // function of greater than, then insert 2 elements
    map <int, int, less<int> > m2;
    m2.insert(Int_Pair(1, 10));
    m2.insert(Int_Pair(2, 20));

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

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

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

    // Create a map m6 by copying the range m4[ first,  last)
    // and with the allocator of map m2
    map <int, int>::allocator_type m2_Alloc;
    m2_Alloc = m2.get_allocator();
    map <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 map m7 by moving m5
    cout << "m7 =";
    map<int, int> m7(move(m5));
    for (auto i : m7)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    // Create a map m8 by copying in an initializer_list
    map<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 map m9 with an initializer_list and a comparator
    map<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 map m10 with an initializer_list, a comparator, and an allocator
    map<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;
}

`mapped_type`

Um tipo que representa os dados armazenados em um mapa.

typedef Type mapped_type;

Comentários

O tipo mapped_type é um sinônimo para o parâmetro de modelo de Tipo da classe.

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

Exemplo

Confira value_type, para ver um exemplo de como declarar e usar mapped_type.

`max_size`

Retorna o comprimento máximo do mapa.

size_type max_size() const;

Valor de Devolução

O comprimento máximo possível do mapa.

Exemplo

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

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

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

`operator[]`

Insere um elemento em um mapa com um valor de chave especificado.

Type& operator[](const Key& key);

Type& operator[](Key&& key);

Parâmetros

key
O valor da chave do elemento que deve ser inserido.

Valor de Devolução

Uma referência ao valor de dados do elemento inserido.

Comentários

Se o valor da chave do argumento não for encontrado, ele será inserido junto com o valor padrão do tipo de dados.

operator[] pode ser usado para inserir elementos em um mapa m usando m[key] = DataValue;, em que DataValue é o valor de mapped_type do elemento com um valor de chave de key.

Ao usar operator[] para inserir elementos, a referência retornada não indica se uma inserção está alterando um elemento preexistente ou criando outro. As funções membro find e insert podem ser usadas para determinar se um elemento com uma chave especificada já está presente antes de uma inserção.

Exemplo

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

int main( )
{
   using namespace std;
   typedef pair <const int, int> cInt2Int;
   map <int, int> m1;
   map <int, int> :: iterator pIter;

   // Insert a data value of 10 with a key of 1
   // into a map using the operator[] member function
   m1[ 1 ] = 10;

   // Compare other ways to insert objects into a map
   m1.insert ( map <int, int> :: value_type ( 2, 20 ) );
   m1.insert ( cInt2Int ( 3, 30 ) );

   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;

   // If the key already exists, operator[]
   // changes the value of the datum in the element
   m1[ 2 ] = 40;

   // operator[] will also insert the value of the data
   // type's default constructor if the value is unspecified
   m1[5];

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

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

// insert by moving key
    map<string, int> c2;
    string str("abc");
    cout << "c2[move(str)] == " << c2[move(str)] << endl;
    cout << "c2["abc"] == " << c2["abc"] << endl;

    return (0);
}

The keys of the mapped elements are: 1 2 3.
The values of the mapped elements are: 10 20 30.
The keys of the mapped elements are now: 1 2 3 5.
The values of the mapped elements are now: 10 40 30 0.
c2[move(str)] == 0
c2["abc"] == 1

`operator=`

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

map& operator=(const map& right);
map& operator=(map&& right);

Parâmetros

right
O map que está sendo copiado no map.

Comentários

Após apagar qualquer elemento existente em um map, o operator= copia ou move o conteúdo do right para o mapa.

Exemplo

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

int main( )
   {
   using namespace std;
   map<int, int> v1, v2, v3;
   map<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;
   }

`pointer`

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

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 de mapa.

rbegin

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

const_reverse_iterator rbegin() const;

reverse_iterator rbegin();

Valor de Devolução

Um iterador bidirecional inverso, que trata o primeiro elemento em um mapa invertido ou trata o que foi o último elemento no mapa não invertido.

Comentários

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

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

rbegin pode ser usado para iterar em versões anteriores de um mapa.

Exemplo

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

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

   map <int, int> :: iterator m1_Iter;
   map <int, int> :: reverse_iterator m1_rIter;
   map <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 map m1 is "
        << m1_rIter -> first << "." << endl;

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

   // A map element can be erased by dereferencing to 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 map is "
        << m1_rIter -> first << "." << endl;
}

The first element of the reversed map m1 is 3.
The map is: 1 2 3 .
The reversed map is: 3 2 1 .
After the erasure, the first element in the reversed map is 2.

`reference`

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

typedef typename allocator_type::reference reference;

Exemplo

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

int main( )
{
   using namespace std;
   map <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 map 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 map 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 map is 1.
The data value of first element in the map is 10.
The modified data value of first element is 15.

`rend`

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

const_reverse_iterator rend() const;

reverse_iterator rend();

Valor de Devolução

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

Comentários

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

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

rend pode ser usado para testar se um iterador inverso alcançou o final de seu mapa.

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

Exemplo

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

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

   map <int, int> :: iterator m1_Iter;
   map <int, int> :: reverse_iterator m1_rIter;
   map <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 map m1 is "
        << m1_rIter -> first << "." << endl;

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

   // A map 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 map is "
        << m1_rIter -> first << "." << endl;
}

The last element of the reversed map m1 is 1.
The map is: 1 2 3 .
The reversed map is: 3 2 1 .
After the erasure, the last element in the reversed map is 2.

`reverse_iterator`

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

typedef std::reverse_iterator<iterator> reverse_iterator;

Comentários

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

O reverse_iterator definido pelo mapa aponta para elementos que são objetos de value_type, que são do tipo pair<const Key, Type>, cujo primeiro membro é a chave para o elemento e o segundo membro é a referência mapeada mantida pelo elemento.

Para desreferenciar um reverse_iteratorrIter apontando para um elemento em um mapa, 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). first.

Exemplo

Confira rbegin, para ver um exemplo de como declarar e usar reverse_iterator.

`size`

Retorna o número de elementos no map.

size_type size() const;

Valor de Devolução

O comprimento atual do mapa.

Exemplo

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

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

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

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

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

The map length is 1.
The map length is now 2.

`size_type`

Um tipo de inteiro sem sinal, que pode representar o número de elementos em um mapa.

typedef typename allocator_type::size_type size_type;

Exemplo

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

troca

Troca os elementos de dois mapas.

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

Parâmetros

right
O mapa de argumentos que fornece os elementos a serem trocados com o mapa de destino.

Comentários

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

Exemplo

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

int main( )
{
   using namespace std;
   map <int, int> m1, m2, m3;
   map <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 map 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
   //m2 is said to be the argument map; m1 the target map
   m1.swap( m2 );

   cout << "After swapping with m2, map 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, map m1 is:";
   for ( m1_Iter = m1.begin( ); m1_Iter != m1.end( ); m1_Iter++ )
      cout << " " << m1_Iter -> second;
   cout   << "." << endl;
}

The original map m1 is: 10 20 30.
After swapping with m2, map m1 is: 100 200.
After swapping with m3, map m1 is: 300.

`upper_bound`

Retorna um iterador para o primeiro elemento de um mapa com uma chave cujo valor é maior que aquele de uma chave especificada.

iterator upper_bound(const Key& key);

const_iterator upper_bound(const Key& key) const;

Parâmetros

key
O valor de chave do argumento a ser comparado com o valor da chave de classificação de um elemento do mapa que está sendo pesquisado.

Valor de Devolução

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

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

Exemplo

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

int main( )
{
   using namespace std;
   map <int, int> m1;
   map <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_RcIter = m1.upper_bound( 2 );
   cout << "The first element of map 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. upper_bound ( 4 );

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

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

The first element of map m1 with a key greater than 2 is: 30.
The map m1 doesn't have an element with a key greater than 4.
The 1st element of m1 with a key greater than
that of the initial element of m1 is: 20.

`value_comp`

A função membro retorna um objeto de função que determina a ordem dos elementos em um mapa ao comparar seus valores de chave.

value_compare value_comp() const;

Valor de Devolução

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

Comentários

Para um mapa m, se dois elementos e1(k1, d1) e e2(k2, d2) forem do tipo value_type, cujos k1 e k1 são as chaves do tipo key_type, e d1 e d2 são dados do tipo mapped_type, então m.value_comp(e1, e2) será equivalente a m.key_comp(k1, k2). Um objeto armazenado define a função de membro

bool operator( value_type& left, value_type& right);

que retornará true se o valor de chave left for precedente e for diferente do valor de chave de right na ordem de classificação.

Exemplo

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

int main( )
{
   using namespace std;

   map <int, int, less<int> > m1;
   map <int, int, less<int> >::value_compare vc1 = m1.value_comp( );
   pair< map<int,int>::iterator, bool > pr1, pr2;

   pr1= m1.insert ( map <int, int> :: value_type ( 1, 10 ) );
   pr2= m1.insert ( map <int, int> :: value_type ( 2, 5 ) );

   if( vc1( *pr1.first, *pr2.first ) == 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( *pr2.first, *pr1.first ) == 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 ).

`value_type`

O tipo de objeto armazenado como um elemento em um mapa.

typedef pair<const Key, Type> value_type;

Exemplo

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

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

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

   // Compare other ways to insert objects into a map
   m1.insert ( cInt2Int ( 2, 20 ) );
   m1[ 3 ] = 30;

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

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

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

   // The following line would cause an error because
   // the value_type isn't 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;
}

Confira também

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

Classe map

Sintaxe

Parâmetros

Comentários

Membros

Construtores

Typedefs

Funções de membro

Operadores

allocator_type

Exemplo

at

Parâmetros

Valor de Devolução

Comentários

Exemplo

begin

Valor de Devolução

Exemplo

cbegin

Valor de Devolução

Comentários

cend

Valor de Devolução

Comentários

clear

Exemplo

const_iterator

Comentários

Exemplo

const_pointer

Comentários

const_reference

Exemplo

const_reverse_iterator

Comentários

Exemplo

count

Parâmetros

Valor de Devolução

Comentários

Exemplo

contains

Parâmetros

Valor de Devolução

Comentários

Exemplo

crbegin

Valor de Devolução

Comentários

Exemplo

crend

Valor de Devolução

Comentários

Exemplo

difference_type

Comentários

Exemplo

emplace

Parâmetros

Valor de Devolução

Comentários

Exemplo

emplace_hint

Parâmetros

Valor de Devolução

Comentários

Exemplo

empty

Valor de Devolução

Exemplo

end

Valor de Devolução

Comentários

equal_range

Parâmetros

Valor de Devolução

Exemplo

erase

Parâmetros

Classe `map`

`allocator_type`

`at`

`begin`

`cbegin`

`cend`

`clear`

`const_iterator`

`const_pointer`

`const_reference`

`const_reverse_iterator`

`count`

`contains`

`crbegin`

`crend`

`difference_type`

`emplace`

`emplace_hint`

`empty`

`end`

`equal_range`

`erase`

`find`

`get_allocator`

`insert`

`iterator`

`key_comp`

`key_compare`

`key_type`

`lower_bound`

`map`

`mapped_type`

`max_size`

`operator[]`

`operator=`

`pointer`

`reference`

`rend`

`reverse_iterator`

`size`