Classe `CMap`

Articolo
10/12/2023

Classe Collection dizionario che esegue il mapping delle chiavi univoche ai valori.

Sintassi

template<class KEY, class ARG_KEY, class VALUE, class ARG_VALUE>class CMap : public CObject

Parametri

KEY
Classe dell'oggetto utilizzato come chiave per la mappa.

ARG_KEY
Tipo di dati utilizzato per KEY gli argomenti; in genere un riferimento a KEY.

VALUE
Classe dell'oggetto archiviato nella mappa.

ARG_VALUE
Tipo di dati utilizzato per VALUE gli argomenti; in genere un riferimento a VALUE.

Membri

Strutture pubbliche

Nome	Descrizione
`CMap::CPair`	Struttura annidata contenente un valore di chiave e il valore dell'oggetto associato.

Costruttori pubblici

Nome	Descrizione
`CMap::CMap`	Costruisce una raccolta che esegue il mapping delle chiavi ai valori.

Metodi pubblici

Nome	Descrizione
`CMap::GetCount`	Restituisce il numero di elementi in questa mappa.
`CMap::GetHashTableSize`	Restituisce il numero di elementi nella tabella hash.
`CMap::GetNextAssoc`	Ottiene l'elemento successivo per l'iterazione.
`CMap::GetSize`	Restituisce il numero di elementi in questa mappa.
`CMap::GetStartPosition`	Restituisce la posizione del primo elemento.
`CMap::InitHashTable`	Inizializza la tabella hash e ne specifica le dimensioni.
`CMap::IsEmpty`	Verifica la condizione della mappa vuota (nessun elemento).
`CMap::Lookup`	Cerca il valore mappato a una determinata chiave.
`CMap::PGetFirstAssoc`	Restituisce un puntatore al primo elemento.
`CMap::PGetNextAssoc`	Ottiene un puntatore all'elemento successivo per l'iterazione.
`CMap::PLookup`	Restituisce un puntatore a una chiave il cui valore corrisponde al valore specificato.
`CMap::RemoveAll`	Rimuove tutti gli elementi da questa mappa.
`CMap::RemoveKey`	Rimuove un elemento specificato da una chiave.
`CMap::SetAt`	Inserisce un elemento nella mappa; sostituisce un elemento esistente se viene trovata una chiave corrispondente.

Operatori pubblici

Nome	Descrizione
`CMap::operator [ ]`	Inserisce un elemento nella mappa , ovvero la sostituzione dell'operatore per `SetAt`.

Osservazioni:

Dopo aver inserito una coppia chiave-valore (elemento) nella mappa, è possibile recuperare o eliminare in modo efficiente la coppia usando la chiave per accedervi. È anche possibile scorrere tutti gli elementi della mappa.

Una variabile di tipo POSITION viene usata per l'accesso alternativo alle voci. È possibile usare un POSITION oggetto per "ricordare" una voce e per scorrere la mappa. Si potrebbe pensare che questa iterazione sia sequenziale in base al valore della chiave; non è così. La sequenza di elementi recuperati è indeterminato.

Alcune funzioni membro di questa classe chiamano funzioni helper globali che devono essere personalizzate per la maggior parte degli usi della CMap classe . Vedere Collection Class Helpers (Helper di classi di raccolta) nella sezione Macro e Globals (Globals) della Guida di riferimento per MFC.

CMap esegue l'override CObject::Serialize per supportare la serializzazione e il dump dei relativi elementi. Se una mappa viene archiviata in un archivio usando Serialize, ogni elemento della mappa viene serializzato a sua volta. L'implementazione predefinita della SerializeElements funzione helper esegue una scrittura bit per bit. Per informazioni sulla serializzazione degli elementi della raccolta di puntatori derivati da CObject o altri tipi definiti dall'utente, vedere Procedura: Creare una raccolta indipendente dai tipi.

Se è necessario un dump di diagnostica dei singoli elementi nella mappa (chiavi e valori), è necessario impostare la profondità del contesto di dump su 1 o versione successiva.

Quando un CMap oggetto viene eliminato o quando i relativi elementi vengono rimossi, le chiavi e i valori vengono rimossi entrambi.

La derivazione della classe Map è simile alla derivazione list. Vedere l'articolo Raccolte per un'illustrazione della derivazione di una classe di elenco per scopi speciali.

Gerarchia di ereditarietà

CObject

CMap

Requisiti

Intestazione: afxtempl.h

`CMap::CMap`

Costruisce una mappa vuota.

CMap(INT_PTR nBlockSize = 10);

Parametri

nBlockSize
Specifica la granularità di allocazione della memoria per estendere la mappa.

Osservazioni:

Man mano che la mappa aumenta, la memoria viene allocata in unità di nBlockSize voci.

Esempio

// declares a map of ints to points
CMap<int, int, CPoint, CPoint> myMap(16);

`CMap::CPair`

Contiene un valore di chiave e il valore dell'oggetto associato.

Osservazioni:

Si tratta di una struttura annidata all'interno della classe CMap.

La struttura è costituita da due campi:

key Valore effettivo del tipo di chiave.
value Valore dell'oggetto associato.

Viene usato per archiviare i valori restituiti da CMap::PLookup, CMap::PGetFirstAssoce CMap::PGetNextAssoc.

Esempio

Per un esempio di utilizzo, vedere l'esempio per CMap::PLookup.

`CMap::GetCount`

Recupera il numero di elementi nella mappa.

INT_PTR GetCount() const;

Valore restituito

Numero di elementi.

Esempio

Vedere l'esempio per CMap::Lookup.

`CMap::GetHashTableSize`

Determina il numero di elementi nella tabella hash per la mappa.

UINT GetHashTableSize() const;

Valore restituito

Numero di elementi nella tabella hash.

Esempio

CMap<int, int, CPoint, CPoint> myMap;

UINT uTableSize = myMap.GetHashTableSize();

`CMap::GetNextAssoc`

Recupera l'elemento della mappa in rNextPosition, quindi aggiorna rNextPosition per fare riferimento all'elemento successivo nella mappa.

void GetNextAssoc(
    POSITION& rNextPosition,
    KEY& rKey,
    VALUE& rValue) const;

Parametri

rNextPosition
Specifica un riferimento a un POSITION valore restituito da una chiamata o GetStartPosition precedenteGetNextAssoc.

KEY
Parametro del modello che specifica il tipo della chiave della mappa.

rKey
Specifica la chiave restituita dell'elemento recuperato.

VALUE
Parametro di modello che specifica il tipo del valore della mappa.

rValue
Specifica il valore restituito dell'elemento recuperato.

Osservazioni:

Questa funzione è più utile per scorrere tutti gli elementi della mappa. Si noti che la sequenza di posizione non corrisponde necessariamente alla sequenza di valori della chiave.

Se l'elemento recuperato è l'ultimo nella mappa, il nuovo valore di rNextPosition viene impostato su NULL.

Esempio

Vedere l'esempio per CMap::SetAt.

`CMap::GetSize`

Restituisce il numero di elementi della mappa.

INT_PTR GetSize() const;

Valore restituito

Numero di elementi nella mappa.

Osservazioni:

Chiamare questo metodo per recuperare il numero di elementi nella mappa.

Esempio

CMap<int, int, CPoint, CPoint> myMap;

myMap.InitHashTable(257);

// Add 200 elements to the map.
for (int i = 0; i < 200; i++)
{
   myMap[i] = CPoint(i, i);
}

// Remove the elements with even key values.
CPoint pt;
for (int i = 0; myMap.Lookup(i, pt); i += 2)
{
   myMap.RemoveKey(i);
}

ASSERT(myMap.GetSize() == 100);
TRACE(_T("myMap with %d elements:\n"), myMap.GetCount());
POSITION pos = myMap.GetStartPosition();
int iKey;
CPoint ptVal;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, iKey, ptVal);
   TRACE(_T("\t[%d] = (%d,%d)\n"), iKey, ptVal.x, ptVal.y);
}

`CMap::GetStartPosition`

Avvia un'iterazione della mappa restituendo un POSITION valore che può essere passato a una GetNextAssoc chiamata.

POSITION GetStartPosition() const;

Valore restituito

Valore POSITION che indica una posizione iniziale per l'iterazione della mappa oppure NULL se la mappa è vuota.

Osservazioni:

La sequenza di iterazione non è prevedibile; pertanto, il "primo elemento nella mappa" non ha un significato speciale.

Esempio

Vedere l'esempio per CMap::SetAt.

`CMap::InitHashTable`

Inizializza la tabella hash.

void InitHashTable(UINT hashSize, BOOL  bAllocNow = TRUE);

Parametri

hashSize
Numero di voci nella tabella hash.

bAllocNow
Se TRUE, alloca la tabella hash all'inizializzazione; in caso contrario, la tabella viene allocata quando necessario.

Osservazioni:

Per ottenere prestazioni ottimali, le dimensioni della tabella hash devono essere un numero primo. Per ridurre al minimo le collisioni, le dimensioni devono essere approssimativamente superiori al 20% rispetto al set di dati previsto più grande.

Esempio

Vedere l'esempio per CMap::Lookup.

`CMap::IsEmpty`

Determina se la mappa è vuota.

BOOL IsEmpty() const;

Valore restituito

Diverso da zero se la mappa non contiene elementi; in caso contrario, 0.

Esempio

Vedere l'esempio per CMap::RemoveAll.

`CMap::Lookup`

Cerca il valore mappato a una determinata chiave.

BOOL Lookup(ARG_KEY key, VALUE& rValue) const;

Parametri

ARG_KEY
Parametro del modello che specifica il tipo del key valore.

key
Specifica la chiave che identifica l'elemento da cercare.

VALUE
Specifica il tipo del valore da cercare.

rValue
Riceve il valore cercato.

Valore restituito

Diverso da zero se l'elemento è stato trovato; in caso contrario, 0.

Osservazioni:

Lookup usa un algoritmo hash per trovare rapidamente l'elemento della mappa con una chiave che corrisponde esattamente alla chiave specificata.

Esempio

CMap<int, int, CPoint, CPoint> myMap;

myMap.InitHashTable(257);

// Add 200 elements to the map.
for (int i = 0; i < 200; i++)
{
   myMap[i] = CPoint(i, i);
}

// Remove the elements with even key values.
CPoint pt;
for (int i = 0; myMap.Lookup(i, pt); i += 2)
{
   myMap.RemoveKey(i);
}

ASSERT(myMap.GetSize() == 100);
TRACE(_T("myMap with %d elements:\n"), myMap.GetCount());
POSITION pos = myMap.GetStartPosition();
int iKey;
CPoint ptVal;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, iKey, ptVal);
   TRACE(_T("\t[%d] = (%d,%d)\n"), iKey, ptVal.x, ptVal.y);
}

`CMap::operator [ ]`

Un comodo sostituto della SetAt funzione membro.

VALUE& operator[](arg_key key);

Parametri

VALUE
Parametro del modello che specifica il tipo del valore della mappa.

ARG_KEY
Parametro del modello che specifica il tipo del valore della chiave.

key
Chiave utilizzata per recuperare il valore dalla mappa.

Osservazioni:

Può quindi essere usato solo sul lato sinistro di un'istruzione di assegnazione (un valore l). Se non è presente alcun elemento della mappa con la chiave specificata, viene creato un nuovo elemento.

Non esiste alcun "lato destro" (r-value) equivalente a questo operatore perché esiste una possibilità che una chiave non venga trovata nella mappa. Usare la funzione membro per il Lookup recupero degli elementi.

Esempio

Vedere l'esempio per CMap::Lookup.

`CMap::PGetFirstAssoc`

Restituisce la prima voce dell'oggetto mappa.

const CPair* PGetFirstAssoc() const;
CPair* PGetFirstAssoc();

Valore restituito

Puntatore alla prima voce della mappa; vedere CMap::CPair. Se la mappa non contiene voci, il valore è NULL.

Osservazioni:

Chiamare questa funzione per restituire un puntatore al primo elemento dell'oggetto map.

Esempio

typedef CMap<int, int, CPoint, CPoint> CMyMap;
CMyMap myMap;

myMap.InitHashTable(257);

// Add 10 elements to the map.
for (int i = 0; i <= 10; i++)
   myMap.SetAt(i, CPoint(i, i));

// Print the element value with even key values.
int nKey = 0;
CPoint pt;
CMyMap::CPair *pCurVal;

pCurVal = myMap.PGetFirstAssoc();
while (pCurVal != NULL)
{
   if ((nKey % 2) == 0)
   {
      _tprintf_s(_T("Current key value at %d: %d,%d\n"),
                 pCurVal->key, pCurVal->value.x, pCurVal->value.y);
   }
   pCurVal = myMap.PGetNextAssoc(pCurVal);
   nKey++;
}

`CMap::PGetNextAssoc`

Recupera l'elemento della mappa a pAssocReccui punta .

const CPair *PGetNextAssoc(const CPair* pAssocRet) const;

CPair *PGetNextAssoc(const CPair* pAssocRet);

Parametri

pAssocRet
Punta a una voce della mappa restituita da una chiamata o CMap::PGetFirstAssoc precedentePGetNextAssoc.

Valore restituito

Puntatore alla voce successiva nella mappa; vedere CMap::CPair. Se l'elemento è l'ultimo nella mappa, il valore è NULL.

Osservazioni:

Chiamare questo metodo per scorrere tutti gli elementi della mappa. Recuperare il primo elemento con una chiamata a PGetFirstAssoc e quindi scorrere la mappa con chiamate successive a PGetNextAssoc.

Esempio

Vedere l'esempio per CMap::PGetFirstAssoc.

`CMap::PLookup`

Trova il valore mappato a una chiave specificata.

const CPair* PLookup(ARG_KEY key) const;
CPair* PLookup(ARG_KEY key);

Parametri

key
Chiave per l'elemento da cercare.

Valore restituito

Puntatore a una struttura chiave; vedere CMap::CPair. Se non viene trovata alcuna corrispondenza, CMap::PLookup restituisce NULL.

Osservazioni:

Chiamare questo metodo per cercare un elemento della mappa con una chiave che corrisponde esattamente alla chiave specificata.

Esempio

typedef CMap<int, int, CPoint, CPoint> CMyMap;
CMyMap myMap;

myMap.InitHashTable(257);

// Add 10 elements to the map.
for (int i = 0; i <= 10; i++)
   myMap[i] = CPoint(i, i);

// Print the element values with even key values.
CMyMap::CPair *pCurVal;

for (int i = 0; i <= myMap.GetCount(); i += 2)
{
   pCurVal = myMap.PLookup(i);
   _tprintf_s(_T("Current key value at %d: %d,%d\n"),
              pCurVal->key, pCurVal->value.x, pCurVal->value.y);
}

`CMap::RemoveAll`

Rimuove tutti i valori da questa mappa chiamando la funzione DestructElementshelper globale .

void RemoveAll();

Osservazioni:

La funzione funziona correttamente se la mappa è già vuota.

Esempio

CMap<int, int, CPoint, CPoint> myMap;

// Add 10 elements to the map.
for (int i = 0; i < 10; i++)
   myMap.SetAt(i, CPoint(i, i));

myMap.RemoveAll();

ASSERT(myMap.IsEmpty());

`CMap::RemoveKey`

Cerca la voce della mappa corrispondente alla chiave fornita; quindi, se viene trovata la chiave, rimuove la voce.

BOOL RemoveKey(ARG_KEY key);

Parametri

ARG_KEY
Parametro del modello che specifica il tipo della chiave.

key
Chiave per l'elemento da rimuovere.

Valore restituito

Diverso da zero se la voce è stata trovata e rimossa correttamente; in caso contrario, 0.

Osservazioni:

La DestructElements funzione helper viene usata per rimuovere la voce.

Esempio

Vedere l'esempio per CMap::SetAt.

`CMap::SetAt`

Il metodo primario consente di inserire un elemento in una mappa.

void SetAt(ARG_KEY key, ARG_VALUE newValue);

Parametri

ARG_KEY
Parametro del modello che specifica il tipo del key parametro.

key
Specifica la chiave del nuovo elemento.

ARG_VALUE
Parametro del modello che specifica il tipo del newValue parametro.

newValue
Specifica il valore del nuovo elemento.

Osservazioni:

In primo luogo, la chiave viene cercata. Se viene trovata la chiave, il valore corrispondente viene modificato; in caso contrario, viene creata una nuova coppia chiave-valore.

Esempio

CMap<int, int, CPoint, CPoint> myMap;

// Add 10 elements to the map.
for (int i = 0; i < 10; i++)
   myMap.SetAt(i, CPoint(i, i));

// Remove the elements with even key values.
POSITION pos = myMap.GetStartPosition();
int nKey;
CPoint pt;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, nKey, pt);

   if ((nKey % 2) == 0)
      myMap.RemoveKey(nKey);
}

// Print the element values.
pos = myMap.GetStartPosition();
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, nKey, pt);
   _tprintf_s(_T("Current key value at %d: %d,%d\n"),
              nKey, pt.x, pt.y);
}

Vedi anche

Esempio MFC COLLECT
CObject Classe
Grafico della gerarchia

Condividi tramite

Classe CMap

Sintassi

Parametri

Membri

Strutture pubbliche

Costruttori pubblici

Metodi pubblici

Operatori pubblici

Osservazioni:

Gerarchia di ereditarietà

Requisiti

CMap::CMap

Parametri

Osservazioni:

Esempio

CMap::CPair

Osservazioni:

Esempio

CMap::GetCount

Valore restituito

Esempio

CMap::GetHashTableSize

Valore restituito

Esempio

CMap::GetNextAssoc

Parametri

Osservazioni:

Esempio

CMap::GetSize

Valore restituito

Osservazioni:

Esempio

CMap::GetStartPosition

Valore restituito

Osservazioni:

Esempio

CMap::InitHashTable

Parametri

Osservazioni:

Esempio

CMap::IsEmpty

Valore restituito

Esempio

CMap::Lookup

Parametri

Valore restituito

Osservazioni:

Esempio

CMap::operator [ ]

Parametri

Osservazioni:

Esempio

CMap::PGetFirstAssoc

Valore restituito

Osservazioni:

Esempio

CMap::PGetNextAssoc

Parametri

Valore restituito

Osservazioni:

Esempio

CMap::PLookup

Parametri

Valore restituito

Osservazioni:

Esempio

CMap::RemoveAll

Osservazioni:

Esempio

CMap::RemoveKey

Parametri

Valore restituito

Osservazioni:

Esempio

CMap::SetAt

Parametri

Osservazioni:

Esempio

Vedi anche

Classe `CMap`

`CMap::CMap`

`CMap::CPair`

`CMap::GetCount`

`CMap::GetHashTableSize`

`CMap::GetNextAssoc`

`CMap::GetSize`

`CMap::GetStartPosition`

`CMap::InitHashTable`

`CMap::IsEmpty`

`CMap::Lookup`

`CMap::operator [ ]`

`CMap::PGetFirstAssoc`

`CMap::PGetNextAssoc`

`CMap::PLookup`

`CMap::RemoveAll`

`CMap::RemoveKey`

`CMap::SetAt`