CAtlMap – třída
Tato třída poskytuje metody pro vytváření a správu objektu mapy.
Syntaxe
template <typename K,
typename V,
class KTraits = CElementTraits<K>,
class VTraits = CElementTraits<V>>
class CAtlMap
Parametry
K
Typ klíčového prvku.
V
Typ prvku value.
KTraits
Kód použitý ke zkopírování nebo přesunutí klíčových prvků. Další podrobnosti najdete v tématu CElementTraits – třída .
VTraits
Kód použitý ke zkopírování nebo přesunutí hodnotových prvků.
Členové
Veřejné definice typedef
| Jméno | popis |
|---|---|
| CAtlMap::KINARGTYPE | Typ použitý při předání klíče jako vstupního argumentu |
| CAtlMap::KOUTARGTYPE | Typ použitý při vrácení klíče jako výstupního argumentu. |
| CAtlMap::VINARGTYPE | Typ použitý při předání hodnoty jako vstupní argument. |
| CAtlMap::VOUTARGTYPE | Typ použitý při předání hodnoty jako výstupního argumentu. |
Veřejné třídy
| Jméno | popis |
|---|---|
| CAtlMap::CPair – třída | Třída obsahující prvky klíče a hodnoty. |
Datové členy CPair
| Jméno | popis |
|---|---|
| CPair::m_key | Datový člen, který ukládá klíčový prvek. |
| CPair::m_value | Datový člen, který ukládá prvek hodnoty. |
Veřejné konstruktory
| Jméno | popis |
|---|---|
| CAtlMap::CAtlMap | Konstruktor |
| CAtlMap::~CAtlMap | Destruktor. |
Veřejné metody
| Jméno | popis |
|---|---|
| CAtlMap::AssertValid | Voláním této metody způsobíte ASSERT, pokud CAtlMap není platný. |
| CAtlMap::D isableAutoRehash | Voláním této metody zakážete automatické rehashing objektu CAtlMap . |
| CAtlMap::EnableAutoRehash | Voláním této metody povolíte automatické rehashing objektu CAtlMap . |
| CAtlMap::GetAt | Voláním této metody vrátíte prvek na zadané pozici v mapě. |
| CAtlMap::GetCount | Voláním této metody načtěte počet prvků v mapě. |
| CAtlMap::GetHashTableSize | Voláním této metody určíte počet intervalů v tabulce hash mapy. |
| CAtlMap::GetKeyAt | Voláním této metody načtěte klíč uložený na dané pozici v objektu CAtlMap . |
| CAtlMap::GetNext | Voláním této metody získáte ukazatel na další dvojici elementů uloženou v objektu CAtlMap . |
| CAtlMap::GetNextAssoc | Získá další prvek pro iterování. |
| CAtlMap::GetNextKey | Voláním této metody načtěte další klíč z objektu CAtlMap . |
| CAtlMap::GetNextValue | Voláním této metody získáte další hodnotu z objektu CAtlMap . |
| CAtlMap::GetStartPosition | Voláním této metody spustíte iteraci mapování. |
| CAtlMap::GetValueAt | Voláním této metody načtěte hodnotu uloženou na dané pozici v objektu CAtlMap . |
| CAtlMap::InitHashTable | Voláním této metody inicializujete tabulku hash. |
| CAtlMap::IsEmpty | Voláním této metody otestujete prázdný objekt mapy. |
| CAtlMap::Lookup | Voláním této metody vyhledáte klíče nebo hodnoty v objektu CAtlMap . |
| CAtlMap::Rehash | Voláním této metody rehash objektu CAtlMap . |
| CAtlMap::RemoveAll | Voláním této metody odeberete všechny prvky z objektu CAtlMap . |
| CAtlMap::RemoveAtPos | Voláním této metody odeberete prvek na dané pozici v objektu CAtlMap . |
| CAtlMap::RemoveKey | Voláním této metody odeberete prvek z objektu CAtlMap vzhledem ke klíči. |
| CAtlMap::SetAt | Voláním této metody vložíte do mapy dvojici prvků. |
| CAtlMap::SetOptimalLoad | Voláním této metody nastavíte optimální zatížení objektu CAtlMap . |
| CAtlMap::SetValueAt | Voláním této metody změníte hodnotu uloženou na dané pozici v objektu CAtlMap . |
Veřejné operátory
| Jméno | popis |
|---|---|
| CAtlMap::operator[] | Nahradí nebo přidá nový prvek do objektu CAtlMap. |
Poznámky
CAtlMap poskytuje podporu pro mapování pole libovolného daného typu, správu neuspořádaného pole klíčových prvků a jejich přidružených hodnot. Prvky (sestávající z klíče a hodnoty) se ukládají pomocí algoritmu hash, což umožňuje efektivní ukládání a načítání velkého množství dat.
Parametry KTraits a VTraits jsou třídy vlastností, které obsahují jakýkoli doplňkový kód potřebný ke kopírování nebo přesouvání prvků.
Alternativu k CAtlMap tomu nabízí třída CRBMap . CRBMap také ukládá páry klíč/hodnota, ale vykazuje různé charakteristiky výkonu. Doba potřebná k vložení položky, vyhledání klíče nebo odstranění klíče z CRBMap objektu je v protokolu pořadí (n), kde n je počet prvků. Pro CAtlMapvšechny tyto operace obvykle trvá konstantní čas, i když nejhorší scénáře mohou být seřazeny n. Proto je v typickém případě CAtlMap rychlejší.
Druhý rozdíl mezi CRBMap uloženými prvky a CAtlMap je zjevný při iterování uloženými prvky. V , CRBMapprvky jsou navštíveny v seřazené pořadí. V argumentu CAtlMap, prvky nejsou seřazeny a nelze odvodit žádné pořadí.
Pokud je potřeba uložit malý počet prvků, zvažte místo toho použití CSimpleMap třídy.
Další informace naleznete v tématu ATL Collection Classes.
Požadavky
Hlavička: atlcoll.h
CAtlMap::AssertValid
Voláním této metody způsobí ASSERT, pokud CAtlMap objekt není platný.
void AssertValid() const;
Poznámky
V sestavení ladění tato metoda způsobí ASSERT, pokud CAtlMap objekt není platný.
Příklad
Podívejte se na příklad pro CAtlMap::CAtlMap.
CAtlMap::CAtlMap
Konstruktor
CAtlMap(
UINT nBins = 17,
float fOptimalLoad = 0.75f,
float fLoThreshold = 0.25f,
float fHiThreshold = 2.25f,
UINT nBlockSize = 10) throw ();
Parametry
nBiny
Počet intervalů poskytujících ukazatele na uložené prvky. Vysvětlení přihrádek najdete v poznámkách dále v tomto tématu.
fOptimalLoad
Optimální poměr zatížení.
fLoThreshold
Nižší prahová hodnota poměru zatížení.
fHiThreshold
Horní prahová hodnota poměru zatížení.
nBlockSize
Velikost bloku.
Poznámky
CAtlMap odkazuje na všechny jeho uložené prvky tak, že nejprve vytvoří index pomocí algoritmu hash klíče. Tento index odkazuje na "bin", který obsahuje ukazatel na uložené elementy. Pokud se koš už používá, vytvoří se propojený seznam pro přístup k dalším prvkům. Procházení seznamu je pomalejší než přímý přístup ke správnému prvku, takže struktura mapy musí vyrovnávat požadavky na úložiště s výkonem. Ve většině případů jsme zvolili výchozí parametry, aby poskytovaly dobré výsledky.
Poměr zatížení je poměr počtu intervalů k počtu prvků uložených v objektu mapy. Při přepočtu struktury mapy se k výpočtu požadovaného počtu intervalů použije hodnota parametru fOptimalLoad . Tuto hodnotu lze změnit pomocí CAtlMap::SetOptimalLoad metoda.
Parametr fLoThreshold je nižší hodnota, na kterou může poměr zatížení dosáhnout, než CAtlMap se přepočítá optimální velikost mapy.
Parametr fHiThreshold je horní hodnota, kterou může poměr zatížení dosáhnout před CAtlMap tím, než objekt přepočítá optimální velikost mapy.
Tento proces přepočtu (označovaný jako rehashing) je ve výchozím nastavení povolený. Pokud chcete tento proces zakázat, například při zadávání velkého množství dat najednou, zavolejte CAtlMap::D isableAutoRehash metoda. Znovu ho aktivujte pomocí metody CAtlMap::EnableAutoRehash .
NBlockSize parametr je míra množství paměti přidělené v případě, že je požadován nový prvek. Větší velikosti bloků snižují počet volání rutin přidělení paměti, ale využívají více prostředků.
Před uložením jakýchkoli dat je nutné inicializovat tabulku hash voláním CAtlMap::InitHashTable.
Příklad
// Create a map which stores a double
// value using an integer key
CAtlMap<int, double> mySinTable;
int i;
// Initialize the Hash Table
mySinTable.InitHashTable(257);
// Add items to the map
for (i = 0; i < 90; i++)
mySinTable[i] = sin((double)i);
// Confirm the map is valid
mySinTable.AssertValid();
// Confirm the number of elements in the map
ATLASSERT(mySinTable.GetCount() == 90);
// Remove elements with even key values
for (i = 0; i < 90; i += 2)
mySinTable.RemoveKey(i);
// Confirm the number of elements in the map
ATLASSERT(mySinTable.GetCount() == 45);
// Walk through all the elements in the map.
// First, get start position.
POSITION pos;
int key;
double value;
pos = mySinTable.GetStartPosition();
// Now iterate the map, element by element
while (pos != NULL)
{
key = mySinTable.GetKeyAt(pos);
value = mySinTable.GetNextValue(pos);
}
CAtlMap::~CAtlMap
Destruktor.
~CAtlMap() throw();
Poznámky
Uvolní všechny přidělené prostředky.
CAtlMap::CPair – třída
Třída obsahující prvky klíče a hodnoty.
class CPair : public __POSITION
Poznámky
Tuto třídu používají metody CAtlMap::GetNext a CAtlMap::Lookup pro přístup k elementům klíče a hodnoty uložené ve struktuře mapování.
CAtlMap::D isableAutoRehash
Voláním této metody zakážete automatické rehashing objektu CAtlMap .
void DisableAutoRehash() throw();
Poznámky
Pokud je povolené automatické přemíscení (což je ve výchozím nastavení), počet intervalů v tabulce hash se automaticky přepočítá, pokud hodnota načítání (poměr počtu intervalů k počtu prvků uložených v poli) překročí maximální nebo minimální hodnoty zadané v době vytvoření mapy.
DisableAutoRehash je nejužitečnější, když se na mapu najednou přidá velký počet prvků. Místo aktivace procesu opětovného vytváření dat při každém překročení limitů je efektivnější volat DisableAutoRehash, přidat prvky a nakonec volat CAtlMap::EnableAutoRehash.
CAtlMap::EnableAutoRehash
Voláním této metody povolíte automatické rehashing objektu CAtlMap .
void EnableAutoRehash() throw();
Poznámky
Pokud je povolené automatické přemíscení (což je ve výchozím nastavení), počet intervalů v tabulce hash se automaticky přepočítá, pokud hodnota načítání (poměr počtu intervalů k počtu prvků uložených v poli) překročí maximální nebo minimální hodnoty zadané v okamžiku vytvoření mapy.
EnableAutoRefresh nejčastěji se používá po volání CAtlMap::D isableAutoRehash.
CAtlMap::GetAt
Voláním této metody vrátíte prvek na zadané pozici v mapě.
void GetAt(
POSITION pos,
KOUTARGTYPE key,
VOUTARGTYPE value) const;
CPair* GetAt(POSITION& pos) throw();
Parametry
Pos
Čítač pozice vrácený předchozím voláním CAtlMap::GetNextAssoc nebo CAtlMap::GetStartPosition.
key
Parametr šablony určující typ klíče mapy.
value
Parametr šablony určující typ hodnoty mapy.
Vrácená hodnota
Vrátí ukazatel na aktuální dvojici prvků klíč/hodnota uložených v mapě.
Poznámky
V buildech ladění dojde k chybě kontrolního výrazu, pokud se pos rovná hodnotě NULL.
CAtlMap::GetCount
Voláním této metody načtěte počet prvků v mapě.
size_t GetCount() const throw();
Vrácená hodnota
Vrátí počet prvků v objektu mapy. Jeden prvek je pár klíč/hodnota.
Příklad
Podívejte se na příklad pro CAtlMap::CAtlMap.
CAtlMap::GetHashTableSize
Voláním této metody určíte počet intervalů v tabulce hash mapy.
UINT GetHashTableSize() const throw();
Vrácená hodnota
Vrátí počet intervalů v tabulce hash. Vysvětlení najdete v objektu CAtlMap::CAtlMap.
CAtlMap::GetKeyAt
Voláním této metody načtěte klíč uložený na dané pozici v objektu CAtlMap .
const K& GetKeyAt(POSITION pos) const throw();
Parametry
Pos
Čítač pozice vrácený předchozím voláním CAtlMap::GetNextAssoc nebo CAtlMap::GetStartPosition.
Vrácená hodnota
Vrátí odkaz na klíč uložený na dané pozici v objektu CAtlMap .
Příklad
Podívejte se na příklad pro CAtlMap::CAtlMap.
CAtlMap::GetNext
Voláním této metody získáte ukazatel na další dvojici elementů uloženou v objektu CAtlMap .
CPair* GetNext(POSITION& pos) throw();
const CPair* GetNext(POSITION& pos) const throw();
Parametry
Pos
Čítač pozice vrácený předchozím voláním CAtlMap::GetNextAssoc nebo CAtlMap::GetStartPosition.
Vrácená hodnota
Vrátí ukazatel na další dvojici prvků klíč/hodnota uložených v mapě. Čítač pozice pos se po každém volání aktualizuje. Pokud je načtený prvek poslední v mapě, je hodnota pos nastavená na hodnotu NULL.
CAtlMap::GetNextAssoc
Získá další prvek pro iterování.
void GetNextAssoc(
POSITION& pos,
KOUTARGTYPE key,
VOUTARGTYPE value) const;
Parametry
Pos
Čítač pozice vrácený předchozím voláním CAtlMap::GetNextAssoc nebo CAtlMap::GetStartPosition.
key
Parametr šablony určující typ klíče mapy.
value
Parametr šablony určující typ hodnoty mapy.
Poznámky
Čítač pozice pos se po každém volání aktualizuje. Pokud je načtený prvek poslední v mapě, je hodnota pos nastavená na hodnotu NULL.
CAtlMap::GetNextKey
Voláním této metody načtěte další klíč z objektu CAtlMap .
const K& GetNextKey(POSITION& pos) const throw();
Parametry
Pos
Čítač pozice vrácený předchozím voláním CAtlMap::GetNextAssoc nebo CAtlMap::GetStartPosition.
Vrácená hodnota
Vrátí odkaz na další klíč v mapě.
Poznámky
Aktualizace čítače aktuální pozice, pos. Pokud v mapě nejsou žádné další položky, je čítač pozice nastaven na hodnotu NULL.
CAtlMap::GetNextValue
Voláním této metody získáte další hodnotu z objektu CAtlMap .
V& GetNextValue(POSITION& pos) throw();
const V& GetNextValue(POSITION& pos) const throw();
Parametry
Pos
Čítač pozice vrácený předchozím voláním CAtlMap::GetNextAssoc nebo CAtlMap::GetStartPosition.
Vrácená hodnota
Vrátí odkaz na další hodnotu v mapě.
Poznámky
Aktualizace čítače aktuální pozice, pos. Pokud v mapě nejsou žádné další položky, je čítač pozice nastaven na hodnotu NULL.
Příklad
Podívejte se na příklad pro CAtlMap::CAtlMap.
CAtlMap::GetStartPosition
Voláním této metody spustíte iteraci mapování.
POSITION GetStartPosition() const throw();
Vrácená hodnota
Vrátí počáteční pozici nebo vrátí hodnotu NULL, pokud je mapa prázdná.
Poznámky
Voláním této metody spustíte iteraci mapování vrácením hodnoty POSITION, kterou lze předat metodě GetNextAssoc .
Poznámka
Posloupnost iterací není předvídatelná.
Příklad
Podívejte se na příklad pro CAtlMap::CAtlMap.
CAtlMap::GetValueAt
Voláním této metody načtěte hodnotu uloženou na dané pozici v objektu CAtlMap .
V& GetValueAt(POSITION pos) throw();
const V& GetValueAt(POSITION pos) const throw();
Parametry
Pos
Čítač pozice vrácený předchozím voláním CAtlMap::GetNextAssoc nebo CAtlMap::GetStartPosition.
Vrácená hodnota
Vrátí odkaz na hodnotu uloženou na dané pozici v objektu CAtlMap .
CAtlMap::InitHashTable
Voláním této metody inicializujete tabulku hash.
bool InitHashTable(
UINT nBins,
bool bAllocNow = true);
Parametry
nBiny
Počet intervalů používaných tabulkou hash. Vysvětlení najdete v objektu CAtlMap::CAtlMap.
bAllocNow
Označení příznaku, kdy by měla být přidělena paměť.
Vrácená hodnota
Vrátí hodnotu PRAVDA při úspěšné inicializaci, NEPRAVDA při selhání.
Poznámky
InitHashTable musí být volána před uložením prvků v tabulce hash. Pokud tato metoda není volána explicitně, bude volána automaticky při prvním přidání elementu pomocí počtu přihrádek určený konstruktorem CAtlMap . V opačném případě se mapa inicializuje pomocí nového počtu přihrádek určený parametrem nBins .
Pokud je parametr bAllocNow false, paměť vyžadovaná tabulkou hash nebude přidělena, dokud nebude nejprve požadována. To může být užitečné, pokud si nejste jistí, jestli se mapa použije.
Příklad
Podívejte se na příklad pro CAtlMap::CAtlMap.
CAtlMap::IsEmpty
Voláním této metody otestujete prázdný objekt mapy.
bool IsEmpty() const throw();
Vrácená hodnota
Vrátí hodnotu TRUE, pokud je mapa prázdná, jinak nepravda.
CAtlMap::KINARGTYPE
Typ použitý při předání klíče jako vstupního argumentu.
typedef KTraits::INARGTYPE KINARGTYPE;
CAtlMap::KOUTARGTYPE
Typ použitý při vrácení klíče jako výstupního argumentu.
typedef KTraits::OUTARGTYPE KOUTARGTYPE;
CAtlMap::Lookup
Voláním této metody vyhledáte klíče nebo hodnoty v objektu CAtlMap .
bool Lookup(KINARGTYPE key, VOUTARGTYPE value) const;
const CPair* Lookup(KINARGTYPE key) const throw();
CPair* Lookup(KINARGTYPE key) throw();
Parametry
key
Určuje klíč, který identifikuje prvek, který se má vyhledat.
value
Proměnná, která přijímá vyhledánou hodnotu.
Vrácená hodnota
První forma metody vrátí hodnotu true, pokud je klíč nalezen, jinak false. Druhý a třetí formulář vrátí ukazatel na CPair , který lze použít jako pozici pro volání CAtlMap::GetNext atd.
Poznámky
Lookup používá algoritmus hash k rychlému vyhledání prvku mapy obsahujícího klíč, který přesně odpovídá danému parametru klíče.
CAtlMap::operator []
Nahradí nebo přidá nový prvek do objektu CAtlMap.
V& operator[](kinargtype key) throw();
Parametry
key
Klíč elementu, který chcete přidat nebo nahradit.
Vrácená hodnota
Vrátí odkaz na hodnotu přidruženou k danému klíči.
Příklad
Pokud klíč již existuje, prvek se nahradí. Pokud klíč neexistuje, přidá se nový prvek. Podívejte se na příklad pro CAtlMap::CAtlMap.
CAtlMap::Rehash
Voláním této metody rehash objektu CAtlMap .
void Rehash(UINT nBins = 0);
Parametry
nBiny
Nový počet intervalů, které se mají použít v tabulce hash. Vysvětlení najdete v objektu CAtlMap::CAtlMap.
Poznámky
Pokud je nBins 0, CAtlMap vypočítá přiměřené číslo na základě počtu prvků v mapě a optimálního nastavení zatížení. Za normálních okolností je proces rehashing automatický, ale pokud byl volán CAtlMap::D isableAutoRehash , tato metoda provede potřebnou změnu velikosti.
CAtlMap::RemoveAll
Voláním této metody odeberete všechny prvky z objektu CAtlMap .
void RemoveAll() throw();
Poznámky
Vymaže CAtlMap objekt a uvolní paměť použitou k uložení prvků.
CAtlMap::RemoveAtPos
Voláním této metody odeberete prvek na dané pozici v objektu CAtlMap .
void RemoveAtPos(POSITION pos) throw();
Parametry
Pos
Čítač pozice vrácený předchozím voláním CAtlMap::GetNextAssoc nebo CAtlMap::GetStartPosition.
Poznámky
Odebere dvojici klíč/hodnota uloženou na zadané pozici. Paměť použitá k uložení prvku je uvolněna. Pozice, na kterou odkazuje pos , je neplatná a zatímco pozice všech ostatních prvků v mapě zůstane platná, nemusí nutně zachovat stejné pořadí.
CAtlMap::RemoveKey
Voláním této metody odeberete prvek z objektu CAtlMap vzhledem ke klíči.
bool RemoveKey(KINARGTYPE key) throw();
Parametry
key
Klíč odpovídající páru prvků, který chcete odebrat.
Vrácená hodnota
Vrátí hodnotu TRUE, pokud se klíč najde a odebere, nePRAVDA při selhání.
Příklad
Podívejte se na příklad pro CAtlMap::CAtlMap.
CAtlMap::SetAt
Voláním této metody vložíte do mapy dvojici prvků.
POSITION SetAt(
KINARGTYPE key,
VINARGTYPE value);
Parametry
key
Hodnota klíče, kterou chcete přidat k objektu CAtlMap .
value
Hodnota, kterou chcete přidat k objektu CAtlMap .
Vrácená hodnota
Vrátí pozici dvojice elementů klíč/hodnota v objektu CAtlMap .
Poznámky
SetAt nahradí existující prvek, pokud je nalezen odpovídající klíč. Pokud se klíč nenajde, vytvoří se nový pár klíč/hodnota.
CAtlMap::SetOptimalLoad
Voláním této metody nastavíte optimální zatížení objektu CAtlMap .
void SetOptimalLoad(
float fOptimalLoad,
float fLoThreshold,
float fHiThreshold,
bool bRehashNow = false);
Parametry
fOptimalLoad
Optimální poměr zatížení.
fLoThreshold
Nižší prahová hodnota poměru zatížení.
fHiThreshold
Horní prahová hodnota poměru zatížení.
bRehashNow
Příznak označující, jestli má být tabulka hash přepočítána.
Poznámky
Tato metoda předefinuje optimální hodnotu načtení objektu CAtlMap . Informace o různých parametrech najdete v tématu CAtlMap::CAtlMap . Pokud je argument bRehashNow pravdivý a počet prvků je mimo minimální a maximální hodnoty, tabulka hash se přepočítá.
CAtlMap::SetValueAt
Voláním této metody změníte hodnotu uloženou na dané pozici v objektu CAtlMap .
void SetValueAt(
POSITION pos,
VINARGTYPE value);
Parametry
Pos
Čítač pozice vrácený předchozím voláním CAtlMap::GetNextAssoc nebo CAtlMap::GetStartPosition.
value
Hodnota, kterou chcete přidat k objektu CAtlMap .
Poznámky
Změní prvek hodnoty uložený na dané pozici v objektu CAtlMap .
CAtlMap::VINARGTYPE
Typ použitý při předání hodnoty jako vstupní argument.
typedef VTraits::INARGTYPE VINARGTYPE;
CAtlMap::VOUTARGTYPE
Typ použitý při předání hodnoty jako výstupního argumentu.
typedef VTraits::OUTARGTYPE VOUTARGTYPE;
CAtlMap::CPair::m_key
Datový člen, který ukládá klíčový prvek.
const K m_key;
Parametry
K
Typ klíčového prvku.
CAtlMap::CPair::m_value
Datový člen, který ukládá prvek hodnoty.
V m_value;
Parametry
V
Typ prvku value.
Viz také
Váš názor
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu: https://aka.ms/ContentUserFeedback.
Odeslat a zobrazit názory pro