CAtlMap クラス

[アーティクル]
04/03/2023

このクラスは、マップオブジェクトを作成および管理するためのメソッドを提供します。

構文

template <typename K,
          typename V,
          class KTraits = CElementTraits<K>,
          class VTraits = CElementTraits<V>>
class CAtlMap

パラメーター

K
キー要素の型。

V
値要素の型。

KTraits
キー要素をコピーまたは移動するために使用されるコード。詳細については、「CElementTraits クラス」を参照してください。

VTraits
値要素をコピーまたは移動するために使用されるコード。

メンバー

パブリック typedef

名前	説明
CAtlMap::KINARGTYPE	キーが入力引数として渡される場合に使用される型
CAtlMap::KOUTARGTYPE	キーが出力引数として返される場合に使用される型。
CAtlMap::VINARGTYPE	値が入力引数として渡されるときに使用される型。
CAtlMap::VOUTARGTYPE	値が出力引数として渡されるときに使用される型。

パブリッククラス

名前	説明
CAtlMap::CPair Class	キーと値の要素を含むクラス。

CPair データメンバー

名前	説明
CPair::m_key	キー要素を格納するデータメンバー。
CPair::m_value	値要素を格納するデータメンバー。

パブリックコンストラクター

名前	説明
CAtlMap::CAtlMap	コンストラクター。
CAtlMap::~CAtlMap	デストラクター。

パブリックメソッド

名前	説明
CAtlMap::AssertValid	このメソッドを呼び出すと、`CAtlMap` が無効である場合、ASSERT が生成されます。
CAtlMap::DisableAutoRehash	このメソッドを呼び出すと、`CAtlMap` オブジェクトの自動再ハッシュが無効にされます。
CAtlMap::EnableAutoRehash	このメソッドを呼び出すと、`CAtlMap` オブジェクトの自動再ハッシュが有効にされます。
CAtlMap::GetAt	このメソッドを呼び出すと、マップ内の指定した位置に要素が返されます。
CAtlMap::GetCount	このメソッドを呼び出すと、マップ内の要素の数を取得できます。
CAtlMap::GetHashTableSize	このメソッドを呼び出すと、マップのハッシュテーブル内のビンの数を確認できます。
CAtlMap::GetKeyAt	このメソッドを呼び出すと、`CAtlMap` オブジェクト内の指定した位置に格納されているキーを取得できます。
CAtlMap::GetNext	このメソッドを呼び出すと、`CAtlMap` オブジェクトに格納されている次の要素ペアへのポインターを取得できます。
CAtlMap::GetNextAssoc	次に反復処理の対象となる要素が取得されます。
CAtlMap::GetNextKey	このメソッドを呼び出すと、`CAtlMap` オブジェクトから次のキーを取得できます。
CAtlMap::GetNextValue	このメソッドを呼び出すと、`CAtlMap` オブジェクトから次の値を取得できます。
CAtlMap::GetStartPosition	このメソッドを呼び出すと、マップの反復処理が開始されます。
CAtlMap::GetValueAt	このメソッドを呼び出すと、`CAtlMap` オブジェクト内の指定した位置に格納されている値を取得できます。
CAtlMap::InitHashTable	このメソッドを呼び出すと、ハッシュテーブルが初期化されます。
CAtlMap::IsEmpty	このメソッドを呼び出すと、空のマップオブジェクトがないかどうかをテストすることができます。
CAtlMap::Lookup	このメソッドを呼び出して、`CAtlMap` オブジェクト内のキーまたは値を参照します。
CAtlMap::Rehash	このメソッドを呼び出すと、`CAtlMap` オブジェクトが再ハッシュされます。
CAtlMap::RemoveAll	`CAtlMap` オブジェクトからすべての要素を削除するには、このメソッドを呼び出します。
CAtlMap::RemoveAtPos	このメソッドを呼び出すと、`CAtlMap` オブジェクト内の指定した位置にある要素が削除されます。
CAtlMap::RemoveKey	このメソッドを呼び出し、キーを指定して、`CAtlMap` オブジェクトから要素を削除します。
CAtlMap::SetAt	このメソッドを呼び出すと、マップに要素ペアを挿入できます。
CAtlMap::SetOptimalLoad	このメソッドを呼び出すと、`CAtlMap` オブジェクトの最適な負荷を設定できます。
CAtlMap::SetValueAt	このメソッドを呼び出すと、`CAtlMap` オブジェクト内の指定した位置に格納されている値を変更することができます。

パブリック演算子

名前	説明
CAtlMap::operator[]	要素を置き換えるか、`CAtlMap` に新しい要素を追加します。

解説

CAtlMap では、指定した型のマッピング配列がサポートされます。これにより、キー要素の順序付けられていない配列と、関連する値を管理できます。要素 (キーと値で構成される) は、ハッシュアルゴリズムを使用して格納されます。これにより、大量のデータを効率的に格納および取得できるようになります。

KTraits および VTraits パラメーターは、要素のコピーまたは移動に必要な補足コードを含む特性クラスです。

CAtlMap の代替手段は、CRBMap クラスによって提供されます。 CRBMap によってもキーと値のペアが格納されますが、パフォーマンス特性が異なります。項目の挿入、キーの検索、または CRBMap オブジェクトからのキーの削除にかかる時間は、log(n) 程度となります。ここで、n は要素の数です。 CAtlMap の場合、最悪のシナリオは n 程度になる可能性がありますが、これらの操作のすべてに、通常一定の時間がかかります。そのため、一般的なケースでは、CAtlMap の方が高速です。

CRBMap と CAtlMap とのもう 1 つの相違点は、格納されている要素を反復処理するときに明らかになります。 CRBMap では、要素は並べ替えられた順序でアクセスされます。 CAtlMap では、要素は順序付けされず、順序を推論することはできません。

格納する必要がある要素が少数である場合は、代わりに CSimpleMap クラスを使用することを検討してください。

詳細については、「ATL コレクションクラス」を参照してください。

必要条件

ヘッダー: atlcoll.h

CAtlMap::AssertValid

このメソッドを呼び出すと、CAtlMap オブジェクトが有効でない場合に ASSERT が生成されます。

void AssertValid() const;

解説

デバッグビルドでは、このメソッドを呼び出すと、CAtlMap オブジェクトが無効である場合、ASSERT が生成されます。

例

CAtlMap::CAtlMap の例を参照してください。

CAtlMap::CAtlMap

コンストラクター。

CAtlMap(
    UINT nBins = 17,
    float fOptimalLoad = 0.75f,
    float fLoThreshold = 0.25f,
    float fHiThreshold = 2.25f,
    UINT nBlockSize = 10) throw ();

パラメーター

nBins
格納されている要素へのポインターを提供するビンの数。ビンの説明については、このトピックの後半に記載した「注釈」を参照してください。

fOptimalLoad
最適な負荷比率。

fLoThreshold
負荷比率の下限しきい値。

fHiThreshold
負荷比率の上限しきい値。

nBlockSize
ブロックサイズ。

解説

CAtlMap では、最初にキーに対してハッシュアルゴリズムを使用してインデックスを作成することにより、格納されているその要素をすべて参照します。このインデックスによって、格納されている要素を指すポインターを含む "ビン" が参照されます。ビンが既に使用中である場合は、後続の要素にアクセスするためのリンクリストが作成されます。リストを走査するのは、目的の要素に直接アクセスするよりも低速であるため、マップ構造ではストレージ要件とパフォーマンスのバランスを取る必要があります。ほとんどの場合、既定のパラメーターは適切な結果をもたらすように選択されています。

負荷比率は、マップオブジェクトに格納されている要素の数に対するビン数の比率です。マップ構造が再計算される場合は、必要なビン数を計算するために fOptimalLoad パラメーター値が使用されます。この値を変更するには、CAtlMap::SetOptimalLoad オプションを使用します。

fLoThreshold パラメーターは下限値であり、負荷比率がこの値に達すると、CAtlMap によってマップの最適なサイズが再計算されます。

fHiThreshold パラメーターは上限値であり、負荷比率がこの値に達すると、CAtlMap オブジェクトによってマップの最適なサイズが再計算されます。

この再計算プロセス (再ハッシュと呼ばれます) は、既定で有効になっています。このプロセスを無効にする場合は (一度に大量のデータを入力する場合など)、CAtlMap::DisableAutoRehash メソッドを呼び出します。再アクティブ化するには、CAtlMap::EnableAutoRehash メソッドを使用します。

nBlockSize パラメーターは、新しい要素が必要な場合に割り当てられるメモリ量の測定結果です。ブロックサイズが大きくなると、メモリ割り当てルーチンの呼び出しは減少しますが、より多くのリソースが使用されます。

任意のデータを格納するには、事前に CAtlMap::InitHashTable を呼び出してハッシュテーブルを初期化しておく必要があります。

例

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

デストラクター。

~CAtlMap() throw();

解説

割り当てられたすべてのリソースを解放します。

CAtlMap::CPair クラス

キーと値の要素を含むクラス。

class CPair : public __POSITION

解説

このクラスは、マップ構造体に格納されているキーと値の要素にアクセスするために、CAtlMap::GetNext と CAtlMap::Lookup メソッドによって使用されます。

CAtlMap::DisableAutoRehash

このメソッドを呼び出すと、CAtlMap オブジェクトの自動再ハッシュが無効にされます。

void DisableAutoRehash() throw();

解説

自動再ハッシュが有効になっている場合 (既定値)、負荷値 (配列に格納されている要素の数に対するビンの数の比率) が、マップの作成時に指定された最大値を超えると、または最小値を下回ると、ハッシュテーブル内のビンの数が自動的に再計算されます。

DisableAutoRehash は、多数の要素が一度にマップに追加される場合に最も役立ちます。制限を超えるたびに再ハッシュプロセスをトリガーするのではなく、DisableAutoRehashを呼び出し、要素を追加してから、最後に CAtlMap::EnableAutoRehash を呼び出す方が効率的です。

CAtlMap::EnableAutoRehash

このメソッドを呼び出すと、CAtlMap オブジェクトの自動再ハッシュが有効にされます。

void EnableAutoRehash() throw();

解説

EnableAutoRefresh は、CAtlMap::DisableAutoRehash の呼び出しの後で最もよく使用されます。

CAtlMap::GetAt

このメソッドを呼び出すと、マップ内の指定した位置に要素が返されます。

void GetAt(
    POSITION pos,
    KOUTARGTYPE key,
    VOUTARGTYPE value) const;

CPair* GetAt(POSITION& pos) throw();

パラメーター

pos
CAtlMap::GetNextAssoc または CAtlMap::GetStartPosition の前の呼び出しによって返された位置カウンター。

key
マップのキーの種類を指定するテンプレートパラメーター。

value
マップの値の型を指定するテンプレートパラメーター。

戻り値

マップに格納されているキーと値の要素の現在のペアへのポインターを返します。

解説

デバッグビルドでは、pos が NULL に等しい場合、アサーションエラーが発生します。

CAtlMap::GetCount

このメソッドを呼び出すと、マップ内の要素の数を取得できます。

size_t GetCount() const throw();

戻り値

マップオブジェクト内の要素の数を返します。単一要素はキーと値のペアです。

例

CAtlMap::CAtlMap の例を参照してください。

CAtlMap::GetHashTableSize

このメソッドを呼び出すと、マップのハッシュテーブル内のビンの数を確認できます。

UINT GetHashTableSize() const throw();

戻り値

ハッシュテーブル内のビン数を返します。詳細については、「CAtlMap::CAtlMap」を参照してください。

CAtlMap::GetKeyAt

このメソッドを呼び出すと、CAtlMap オブジェクト内の指定した位置に格納されているキーを取得できます。

const K& GetKeyAt(POSITION pos) const throw();

パラメーター

pos
CAtlMap::GetNextAssoc または CAtlMap::GetStartPosition の前の呼び出しによって返された位置カウンター。

戻り値

CAtlMap オブジェクト内の指定した位置に格納されているキーへの参照を返します。

例

CAtlMap::CAtlMap の例を参照してください。

CAtlMap::GetNext

このメソッドを呼び出すと、CAtlMap オブジェクトに格納されている次の要素ペアへのポインターを取得できます。

CPair* GetNext(POSITION& pos) throw();
const CPair* GetNext(POSITION& pos) const throw();

パラメーター

pos
CAtlMap::GetNextAssoc または CAtlMap::GetStartPosition の前の呼び出しによって返された位置カウンター。

戻り値

マップに格納されているキーと値の要素の次のペアへのポインターを返します。 pos 位置カウンターは、各呼び出しの後に更新されます。取得した要素がマップ内の最後の要素である場合、pos は NULL に設定されます。

CAtlMap::GetNextAssoc

次に反復処理の対象となる要素が取得されます。

void GetNextAssoc(
    POSITION& pos,
    KOUTARGTYPE key,
    VOUTARGTYPE value) const;

パラメーター

pos
CAtlMap::GetNextAssoc または CAtlMap::GetStartPosition の前の呼び出しによって返された位置カウンター。

key
マップのキーの種類を指定するテンプレートパラメーター。

value
マップの値の型を指定するテンプレートパラメーター。

解説

pos 位置カウンターは、各呼び出しの後に更新されます。取得した要素がマップ内の最後の要素である場合、pos は NULL に設定されます。

CAtlMap::GetNextKey

このメソッドを呼び出すと、CAtlMap オブジェクトから次のキーを取得できます。

const K& GetNextKey(POSITION& pos) const throw();

パラメーター

pos
CAtlMap::GetNextAssoc または CAtlMap::GetStartPosition の前の呼び出しによって返された位置カウンター。

戻り値

マップ内の次のキーへの参照を返します。

解説

現在の位置カウンター pos を更新します。マップ内にエントリがこれ以上ない場合、位置カウンターは NULL に設定されます。

CAtlMap::GetNextValue

このメソッドを呼び出すと、CAtlMap オブジェクトから次の値を取得できます。

V& GetNextValue(POSITION& pos) throw();
const V& GetNextValue(POSITION& pos) const throw();

パラメーター

pos
CAtlMap::GetNextAssoc または CAtlMap::GetStartPosition の前の呼び出しによって返された位置カウンター。

戻り値

マップ内の次の値への参照を返します。

解説

現在の位置カウンター pos を更新します。マップ内にエントリがこれ以上ない場合、位置カウンターは NULL に設定されます。

例

CAtlMap::CAtlMap の例を参照してください。

CAtlMap::GetStartPosition

このメソッドを呼び出すと、マップの反復処理が開始されます。

POSITION GetStartPosition() const throw();

戻り値

開始位置を返します。マップが空の場合は NULL が返されます。

解説

このメソッドを呼び出すと、GetNextAssoc メソッドに渡すことができる POSITION 値を返すことで、マップの反復処理が開始されます。

Note

反復シーケンスは予測できません

例

CAtlMap::CAtlMap の例を参照してください。

CAtlMap::GetValueAt

このメソッドを呼び出すと、CAtlMap オブジェクト内の指定した位置に格納されている値を取得できます。

V& GetValueAt(POSITION pos) throw();
const V& GetValueAt(POSITION pos) const throw();

パラメーター

pos
CAtlMap::GetNextAssoc または CAtlMap::GetStartPosition の前の呼び出しによって返された位置カウンター。

戻り値

CAtlMap オブジェクト内の特定の位置に格納されている値への参照を返します。

CAtlMap::InitHashTable

このメソッドを呼び出すと、ハッシュテーブルが初期化されます。

bool InitHashTable(
    UINT nBins,
    bool bAllocNow = true);

パラメーター

nBins
ハッシュテーブルによって使用されるビンの数。詳細については、「CAtlMap::CAtlMap」を参照してください。

bAllocNow
メモリを割り当てる必要がある場合のフラグを示します。

戻り値

初期化が成功した場合は TRUE、失敗した場合は FALSE を返します。

解説

要素がハッシュテーブルに格納される前に、InitHashTable を呼び出す必要があります。このメソッドが明示的に呼び出されない場合は、CAtlMap コンストラクターによって指定されたビン数を使用して要素が初めて追加された場合に自動的に呼び出されます。それ以外の場合、マップは、nBins パラメーターで指定された新しいビン数を使用して初期化されます。

bAllocNow が false の場合、ハッシュテーブルで必要とされるメモリは、最初に必要になるまで割り当てられません。これは、マップが使用されるかどうかが不明な場合に役立ちます。

例

CAtlMap::CAtlMap の例を参照してください。

CAtlMap::IsEmpty

このメソッドを呼び出すと、空のマップオブジェクトがないかどうかをテストすることができます。

bool IsEmpty() const throw();

戻り値

マップが空の場合は TRUE、それ以外の場合は FALSE を返します。

CAtlMap::KINARGTYPE

キーが入力引数として渡されるときに使用される型。

typedef KTraits::INARGTYPE KINARGTYPE;

CAtlMap::KOUTARGTYPE

キーが出力引数として返される場合に使用される型。

typedef KTraits::OUTARGTYPE KOUTARGTYPE;

CAtlMap::Lookup

このメソッドを呼び出して、CAtlMap オブジェクト内のキーまたは値を参照します。

bool Lookup(KINARGTYPE key, VOUTARGTYPE value) const;
const CPair* Lookup(KINARGTYPE key) const throw();
CPair* Lookup(KINARGTYPE key) throw();

パラメーター

key
参照する要素を識別するキーを指定します。

value
参照値を受け取る変数。

戻り値

このメソッドの最初の形式からは、キーが見つかった場合は true、それ以外の場合は false が返されます。 2 番目と 3 番目の形式からは、CPair へのポインターが返されます。これは、CAtlMap::GetNext などの呼び出しの位置として使用できます。

解説

Lookup では、ハッシュアルゴリズムを使用して、指定されたキーパラメーターと完全に一致するキーを含むマップ要素をすばやく検索します。

CAtlMap::operator []

要素を置き換えるか、CAtlMap に新しい要素を追加します。

V& operator[](kinargtype key) throw();

パラメーター

key
追加または置換する要素のキー。

戻り値

指定されたキーに関連付けられている値への参照を返します。

例

キーが既に存在する場合は、要素が置き換えられます。キーが存在しない場合は、新しい要素が追加されます。 CAtlMap::CAtlMap の例を参照してください。

CAtlMap::Rehash

このメソッドを呼び出すと、CAtlMap オブジェクトが再ハッシュされます。

void Rehash(UINT nBins = 0);

パラメーター

nBins
ハッシュテーブルで使用される新しいビン数。詳細については、「CAtlMap::CAtlMap」を参照してください。

解説

nBins が 0 である場合は、CAtlMap によってマップ内の要素の数と最適な読み込み設定に基づいて適切な数が算出されます。通常、再ハッシュプロセスは自動的に行われますが、CAtlMap::DisableAutoRehash が呼び出されている場合は、このメソッドによって必要なサイズ変更が実行されます。

CAtlMap::RemoveAll

CAtlMap オブジェクトからすべての要素を削除するには、このメソッドを呼び出します。

void RemoveAll() throw();

解説

CAtlMap オブジェクトをクリアします。これにより、要素の格納に使用されるメモリが解放されます。

CAtlMap::RemoveAtPos

このメソッドを呼び出すと、CAtlMap オブジェクト内の指定した位置にある要素が削除されます。

void RemoveAtPos(POSITION pos) throw();

パラメーター

pos
CAtlMap::GetNextAssoc または CAtlMap::GetStartPosition の前の呼び出しによって返された位置カウンター。

解説

指定された位置に格納されているキーと値のペアを削除します。要素を格納するのに使用されるメモリが解放されます。 pos によって参照される POSITION が無効になります。マップ内の他の要素の POSITION が有効なままでも、それらは必ずしも同じ順序で保持されるわけではありません。

CAtlMap::RemoveKey

このメソッドを呼び出し、キーを指定して、CAtlMap オブジェクトから要素を削除します。

bool RemoveKey(KINARGTYPE key) throw();

パラメーター

key
削除する要素ペアに対応するキー。

戻り値

キーが見つかって削除した場合は TRUE、失敗した場合は FALSE を返します。

例

CAtlMap::CAtlMap の例を参照してください。

CAtlMap::SetAt

このメソッドを呼び出すと、マップに要素ペアを挿入できます。

POSITION SetAt(
    KINARGTYPE key,
    VINARGTYPE value);

パラメーター

key
CAtlMap オブジェクトに追加するキー値。

value
CAtlMap オブジェクトに追加する値。

戻り値

CAtlMap オブジェクト内のキーと値の要素のペアの位置を返します。

解説

SetAt では、一致するキーが見つかった場合に、既存の要素を置き換えます。キーが見つからない場合は、新しいキーと値のペアが作成されます。

CAtlMap::SetOptimalLoad

このメソッドを呼び出すと、CAtlMap オブジェクトの最適な負荷を設定できます。

void SetOptimalLoad(
    float fOptimalLoad,
    float fLoThreshold,
    float fHiThreshold,
    bool bRehashNow = false);

パラメーター

fOptimalLoad
最適な負荷比率。

fLoThreshold
負荷比率の下限しきい値。

fHiThreshold
負荷比率の上限しきい値。

bRehashNow
ハッシュテーブルを再計算する必要があるかどうかを示すフラグ。

解説

このメソッドでは、CAtlMap オブジェクトに最適な読み込み値を再定義します。各種パラメーターの詳細については、「CAtlMap::CAtlMap」を参照してください。 bRehashNow true であり、要素の数がその最小値から最大値までの範囲の外にある場合、ハッシュテーブルが再計算されます。

CAtlMap::SetValueAt

このメソッドを呼び出すと、CAtlMap オブジェクト内の指定した位置に格納されている値を変更することができます。

void SetValueAt(
    POSITION pos,
    VINARGTYPE value);

パラメーター

pos
CAtlMap::GetNextAssoc または CAtlMap::GetStartPosition の前の呼び出しによって返された位置カウンター。

value
CAtlMap オブジェクトに追加する値。

解説

CAtlMap オブジェクト内の特定の位置に格納されている値の要素を変更します。

CAtlMap::VINARGTYPE

値が入力引数として渡されるときに使用される型。

typedef VTraits::INARGTYPE VINARGTYPE;

CAtlMap::VOUTARGTYPE

値が出力引数として渡されるときに使用される型。

typedef VTraits::OUTARGTYPE VOUTARGTYPE;

CAtlMap::CPair::m_key

キー要素を格納するデータメンバー。

const K m_key;

パラメーター

K
キー要素の型。

CAtlMap::CPair::m_value

値要素を格納するデータメンバー。

V  m_value;

パラメーター

V
値要素の型。

CAtlMap クラス

構文

パラメーター

メンバー

パブリック typedef

パブリック クラス

CPair データ メンバー

パブリック コンストラクター

パブリック メソッド

パブリック演算子

解説

必要条件

CAtlMap::AssertValid

解説

例

CAtlMap::CAtlMap

パラメーター

解説

例

CAtlMap::~CAtlMap

解説

CAtlMap::CPair クラス

解説

CAtlMap::DisableAutoRehash

解説

CAtlMap::EnableAutoRehash

解説

CAtlMap::GetAt

パラメーター

戻り値

解説

CAtlMap::GetCount

戻り値

例

CAtlMap::GetHashTableSize

戻り値

CAtlMap::GetKeyAt

パラメーター

戻り値

例

CAtlMap::GetNext

パラメーター

戻り値

CAtlMap::GetNextAssoc

パラメーター

解説

CAtlMap::GetNextKey

パラメーター

戻り値

解説

CAtlMap::GetNextValue

パラメーター

戻り値

解説

例

CAtlMap::GetStartPosition

戻り値

解説

例

CAtlMap::GetValueAt

パラメーター

戻り値

CAtlMap::InitHashTable

パラメーター

戻り値

解説

例

CAtlMap::IsEmpty

戻り値

CAtlMap::KINARGTYPE

CAtlMap::KOUTARGTYPE

CAtlMap::Lookup

パラメーター

戻り値

解説

CAtlMap::operator []

パラメーター

戻り値

例

CAtlMap::Rehash

パブリッククラス

CPair データメンバー

パブリックコンストラクター

パブリックメソッド