`CMap` Třída

Článek
07/05/2024

Třída kolekce slovníku, která mapuje jedinečné klíče na hodnoty.

Syntaxe

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

Parametry

KEY
Třída objektu použitého jako klíč k mapě.

ARG_KEY
Datový typ použitý pro KEY argumenty; obvykle odkaz na KEY.

VALUE
Třída objektu uloženého v mapě

ARG_VALUE
Datový typ použitý pro VALUE argumenty; obvykle odkaz na VALUE.

Členové

Veřejné struktury

Název	Popis
`CMap::CPair`	Vnořená struktura obsahující hodnotu klíče a hodnotu přidruženého objektu.

Veřejné konstruktory

Název	Popis
`CMap::CMap`	Vytvoří kolekci, která mapuje klíče na hodnoty.

Veřejné metody

Název	Popis
`CMap::GetCount`	Vrátí počet prvků v této mapě.
`CMap::GetHashTableSize`	Vrátí počet prvků v tabulce hash.
`CMap::GetNextAssoc`	Získá další prvek pro iterování.
`CMap::GetSize`	Vrátí počet prvků v této mapě.
`CMap::GetStartPosition`	Vrátí pozici prvního prvku.
`CMap::InitHashTable`	Inicializuje tabulku hash a určuje její velikost.
`CMap::IsEmpty`	Testuje podmínku prázdné mapy (žádné prvky).
`CMap::Lookup`	Vyhledá hodnotu namapovanou na daný klíč.
`CMap::PGetFirstAssoc`	Vrátí ukazatel na první prvek.
`CMap::PGetNextAssoc`	Získá ukazatel na další prvek pro iterování.
`CMap::PLookup`	Vrátí ukazatel na klíč, jehož hodnota odpovídá zadané hodnotě.
`CMap::RemoveAll`	Odebere všechny prvky z této mapy.
`CMap::RemoveKey`	Odebere prvek určený klíčem.
`CMap::SetAt`	Vloží prvek do mapy; nahradí existující prvek, pokud je nalezen odpovídající klíč.

Veřejné operátory

Název	Popis
`CMap::operator [ ]`	Vloží prvek do mapy – nahrazení operátoru `SetAt`.

Poznámky

Po vložení páru klíč-hodnota (element) do mapy můžete dvojici efektivně načíst nebo odstranit pomocí klíče, abyste k němu získali přístup. Můžete také iterovat všechny prvky v mapě.

Proměnná typu POSITION se používá pro alternativní přístup k položkám. Položku si můžete POSITION zapamatovat a iterovat pomocí mapy. Možná si myslíte, že tato iterace je sekvenční podle hodnoty klíče; to není. Posloupnost načtených prvků je neurčitá.

Některé členské funkce této třídy volají globální pomocné funkce, které musí být přizpůsobeny pro většinu použití CMap třídy. Viz Pomocné rutiny třídy kolekce v části Makra a globální hodnoty v referenční dokumentaci MFC.

CMap přepsání CObject::Serialize na podporu serializace a dumpingu jejích prvků. Pokud je mapa uložena do archivu pomocí Serialize, každý prvek mapy je serializován postupně. Výchozí implementace SerializeElements pomocné funkce provede bitové zápisy. Informace o serializaci položek kolekce ukazatelů odvozených z CObject nebo jiných uživatelem definovaných typů naleznete v tématu Postupy: Vytvoření kolekce typu bezpečné.

Pokud potřebujete diagnostický výpis jednotlivých prvků v mapě (klíče a hodnoty), musíte nastavit hloubku kontextu výpisu na hodnotu 1 nebo vyšší.

Při odstranění objektu CMap nebo při odebrání jeho prvků se klíče a hodnoty odeberou.

Odvození třídy mapování se podobá odvození seznamu. Na obrázku odvození třídy seznamu pro zvláštní účely najdete v článku Kolekce .

Hierarchie dědičnosti

CObject

CMap

Požadavky

Záhlaví: afxtempl.h

`CMap::CMap`

Vytvoří prázdnou mapu.

CMap(INT_PTR nBlockSize = 10);

Parametry

nBlockSize
Určuje členitost přidělení paměti pro rozšíření mapy.

Poznámky

S rostoucím nárůstem mapy se paměť přiděluje v jednotkách nBlockSize položek.

Příklad

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

`CMap::CPair`

Obsahuje hodnotu klíče a hodnotu přidruženého objektu.

Poznámky

Jedná se o vnořenou strukturu v rámci třídy CMap.

Struktura se skládá ze dvou polí:

key Skutečná hodnota typu klíče.
value Hodnota přidruženého objektu.

Slouží k ukládání vrácených hodnot z CMap::PLookup, CMap::PGetFirstAssoca CMap::PGetNextAssoc.

Příklad

Příklad použití najdete v příkladu .CMap::PLookup

`CMap::GetCount`

Načte počet prvků v mapě.

INT_PTR GetCount() const;

Návratová hodnota

Počet prvků.

Příklad

Podívejte se na příklad pro CMap::Lookup.

`CMap::GetHashTableSize`

Určuje počet prvků v tabulce hash pro mapu.

UINT GetHashTableSize() const;

Návratová hodnota

Počet prvků v tabulce hash

Příklad

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

UINT uTableSize = myMap.GetHashTableSize();

`CMap::GetNextAssoc`

Načte prvek mapy na a rNextPositionpak aktualizuje rNextPosition odkaz na další prvek v mapě.

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

Parametry

rNextPosition
Určuje odkaz na POSITION hodnotu vrácenou předchozím GetNextAssoc voláním nebo GetStartPosition voláním.

KEY
Parametr šablony určující typ klíče mapy.

rKey
Určuje vrácený klíč načteného prvku.

VALUE
Parametr šablony určující typ hodnoty mapy.

rValue
Určuje vrácenou hodnotu načteného prvku.

Poznámky

Tato funkce je nejužitečnější pro iteraci všemi prvky v mapě. Všimněte si, že pořadí pozic nemusí být nutně stejné jako posloupnost klíčových hodnot.

Pokud je načtený prvek poslední v mapě, pak je nová hodnota rNextPosition nastavena na NULL.

Příklad

Podívejte se na příklad pro CMap::SetAt.

`CMap::GetSize`

Vrátí počet prvků mapy.

INT_PTR GetSize() const;

Návratová hodnota

Počet položek v mapě.

Poznámky

Voláním této metody načtěte počet prvků v mapě.

Příklad

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`

Spustí iteraci mapy vrácením POSITION hodnoty, kterou lze předat GetNextAssoc volání.

POSITION GetStartPosition() const;

Návratová hodnota

Hodnota POSITION , která označuje počáteční pozici pro iteraci mapy, nebo NULL pokud je mapa prázdná.

Poznámky

Posloupnost iterací není předvídatelná; proto "první prvek v mapě" nemá žádný zvláštní význam.

Příklad

Podívejte se na příklad pro CMap::SetAt.

`CMap::InitHashTable`

Inicializuje tabulku hash.

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

Parametry

hashSize
Počet položek v tabulce hash

bAllocNow
Pokud TRUEpři inicializaci přiděluje hashovací tabulku, v opačném případě je tabulka přidělena v případě potřeby.

Poznámky

Pro zajištění nejlepšího výkonu by velikost tabulky hash měla být primárním číslem. Aby se minimalizovaly kolize, měla by být velikost přibližně 20 % větší než největší očekávaná datová sada.

Příklad

Podívejte se na příklad pro CMap::Lookup.

`CMap::IsEmpty`

Určuje, zda je mapa prázdná.

BOOL IsEmpty() const;

Návratová hodnota

Nenulové, pokud tato mapa neobsahuje žádné prvky; jinak 0.

Příklad

Podívejte se na příklad pro CMap::RemoveAll.

`CMap::Lookup`

Vyhledá hodnotu namapovanou na daný klíč.

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

Parametry

ARG_KEY
Parametr šablony určující typ key hodnoty.

key
Určuje klíč, který identifikuje prvek, který se má vyhledat.

VALUE
Určuje typ hodnoty, která se má vyhledat.

rValue
Získá hledaná hodnota.

Návratová hodnota

Nenulové, pokud byl prvek nalezen; jinak 0.

Poznámky

Lookup používá algoritmus hash k rychlému vyhledání prvku mapy s klíčem, který přesně odpovídá danému klíči.

Příklad

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 [ ]`

Pohodlná náhrada členské SetAt funkce.

VALUE& operator[](arg_key key);

Parametry

VALUE
Parametr šablony určující typ hodnoty mapy.

ARG_KEY
Parametr šablony určující typ hodnoty klíče

key
Klíč použitý k načtení hodnoty z mapy.

Poznámky

Lze jej tedy použít pouze na levé straně příkazu přiřazení (l-hodnota). Pokud neexistuje žádný prvek mapování se zadaným klíčem, vytvoří se nový prvek.

Neexistuje žádná "pravá strana" (r-value) ekvivalentní tomuto operátoru, protože existuje možnost, že klíč nelze v mapě najít. Pro načtení elementu Lookup použijte členovou funkci.

Příklad

Podívejte se na příklad pro CMap::Lookup.

`CMap::PGetFirstAssoc`

Vrátí první položku objektu mapy.

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

Návratová hodnota

Ukazatel na první položku v mapě; viz .CMap::CPair Pokud mapa neobsahuje žádné položky, hodnota je NULL.

Poznámky

Voláním této funkce vrátíte ukazatel prvního prvku v objektu mapy.

Příklad

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`

Načte prvek mapy, na který pAssocRecodkazuje .

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

CPair *PGetNextAssoc(const CPair* pAssocRet);

Parametry

pAssocRet
Odkazuje na položku mapy vrácenou předchozím PGetNextAssoc voláním nebo CMap::PGetFirstAssoc voláním.

Návratová hodnota

Ukazatel na další položku v mapě; viz .CMap::CPair Pokud je prvek poslední v mapě, hodnota je NULL.

Poznámky

Voláním této metody iterujte všechny prvky v mapě. Načtěte první prvek voláním PGetFirstAssoc a pak iterujte mapou s následnými voláními PGetNextAssoc.

Příklad

Podívejte se na příklad pro CMap::PGetFirstAssoc.

`CMap::PLookup`

Vyhledá hodnotu namapovanou na daný klíč.

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

Parametry

key
Klíč pro prvek, který se má vyhledat.

Návratová hodnota

Ukazatel na strukturu klíče; viz .CMap::CPair Pokud se nenajde žádná shoda, CMap::PLookup vrátí hodnotu NULL.

Poznámky

Voláním této metody vyhledejte prvek mapy s klíčem, který přesně odpovídá danému klíči.

Příklad

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`

Odebere všechny hodnoty z této mapy voláním globální pomocné funkce DestructElements.

void RemoveAll();

Poznámky

Funkce funguje správně, pokud je mapa již prázdná.

Příklad

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`

Vyhledá položku mapy odpovídající zadanému klíči; pokud se klíč najde, odebere položku.

BOOL RemoveKey(ARG_KEY key);

Parametry

ARG_KEY
Parametr šablony určující typ klíče

key
Klíč pro prvek, který se má odebrat.

Návratová hodnota

Nenulové, pokud byla položka nalezena a úspěšně odstraněna; jinak 0.

Poznámky

Pomocná DestructElements funkce slouží k odebrání položky.

Příklad

Podívejte se na příklad pro CMap::SetAt.

`CMap::SetAt`

Primárním prostředkem pro vložení elementu do mapy.

void SetAt(ARG_KEY key, ARG_VALUE newValue);

Parametry

ARG_KEY
Parametr šablony určující typ parametru key .

key
Určuje klíč nového prvku.

ARG_VALUE
Parametr šablony určující typ parametru newValue .

newValue
Určuje hodnotu nového prvku.

Poznámky

Za prvé, klíč se hledá. Pokud se klíč najde, změní se odpovídající hodnota; v opačném případě se vytvoří nový pár klíč-hodnota.

Příklad

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

Viz také

Mfc – ukázka COLLECT
CObject Třída
Graf hierarchie

Sdílet prostřednictvím

CMap Třída

Syntaxe

Parametry

Členové

Veřejné struktury

Veřejné konstruktory

Veřejné metody

Veřejné operátory

Poznámky

Hierarchie dědičnosti

Požadavky

CMap::CMap

Parametry

Poznámky

Příklad

CMap::CPair

Poznámky

Příklad

CMap::GetCount

Návratová hodnota

Příklad

CMap::GetHashTableSize

Návratová hodnota

Příklad

CMap::GetNextAssoc

Parametry

Poznámky

Příklad

CMap::GetSize

Návratová hodnota

Poznámky

Příklad

CMap::GetStartPosition

Návratová hodnota

Poznámky

Příklad

CMap::InitHashTable

Parametry

Poznámky

Příklad

CMap::IsEmpty

Návratová hodnota

Příklad

CMap::Lookup

Parametry

Návratová hodnota

Poznámky

Příklad

CMap::operator [ ]

Parametry

Poznámky

Příklad

CMap::PGetFirstAssoc

Návratová hodnota

Poznámky

Příklad

CMap::PGetNextAssoc

Parametry

Návratová hodnota

Poznámky

Příklad

CMap::PLookup

Parametry

Návratová hodnota

Poznámky

Příklad

CMap::RemoveAll

Poznámky

Příklad

CMap::RemoveKey

Parametry

Návratová hodnota

Poznámky

Příklad

CMap::SetAt

Parametry

Poznámky

Příklad

Viz také

`CMap` Třída

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