次の方法で共有


CMap クラス

一意なキーを値に割り当てる辞書コレクション クラスです。

構文

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

パラメーター

KEY
マップのキーとして使用されるオブジェクトのクラス。

ARG_KEY
KEY引数に使用されるデータ型。通常はKEYへの参照です。

VALUE
マップに格納されているオブジェクトのクラス。

ARG_VALUE
VALUE引数に使用されるデータ型。通常はVALUEへの参照です。

メンバー

パブリック構造体

名前 説明
CMap::CPair キー値と関連付けられたオブジェクトの値を含む入れ子になった構造体。

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

名前 説明
CMap::CMap キーを値にマップするコレクションを構築します。

パブリック メソッド

名前 説明
CMap::GetCount このマップ内の要素の数を返します。
CMap::GetHashTableSize ハッシュ テーブル内の要素の数を返します。
CMap::GetNextAssoc 次に反復処理の対象となる要素が取得されます。
CMap::GetSize このマップ内の要素の数を返します。
CMap::GetStartPosition 最初の要素の位置を返します。
CMap::InitHashTable ハッシュ テーブルを初期化し、そのサイズを指定します。
CMap::IsEmpty 空のマップ条件 (要素なし) をテストします。
CMap::Lookup 特定のキーにマップされた値を検索します。
CMap::PGetFirstAssoc 最初の要素へのポインターを返します。
CMap::PGetNextAssoc 反復処理のための次の要素へのポインターを取得します。
CMap::PLookup 指定した値と一致する値を持つキーへのポインターを返します。
CMap::RemoveAll このマップからすべての要素を削除します。
CMap::RemoveKey キーで指定された要素を削除します。
CMap::SetAt マップに要素を挿入します。は、一致するキーが見つかった場合に既存の要素を置き換えます。

パブリック演算子

名前 説明
CMap::operator [ ] map に要素を挿入します。 SetAtの演算子の置換です。

解説

キーと値のペア (要素) をマップに挿入したら、キーを使用してペアを効率的に取得または削除してアクセスできます。 マップ内のすべての要素を反復処理することもできます。

POSITION型の変数は、エントリへの代替アクセスに使用されます。 POSITIONを使用して、エントリを "記憶" し、マップを反復処理できます。 この反復はキー値によって順番に行われると思われるかもしれません。そうじゃないです。 取得された要素のシーケンスは不確定です。

このクラスの特定のメンバー関数は、 CMap クラスのほとんどの用途に合わせてカスタマイズする必要があるグローバル ヘルパー関数を呼び出します。 MFC リファレンスの「マクロとグローバル」セクションの「Collection クラス ヘルパーを参照してください。

CMap は、要素のシリアル化とダンプをサポートするために CObject::Serialize をオーバーライドします。 Serializeを使用してマップがアーカイブに格納されている場合、各マップ要素が順番にシリアル化されます。 SerializeElements ヘルパー関数の既定の実装では、ビットごとの書き込みが行われます。 CObjectまたはその他のユーザー定義型から派生したポインター コレクション項目のシリアル化については、「方法: 型セーフ コレクションを作成する」を参照してください。

マップ内の個々の要素 (キーと値) の診断ダンプが必要な場合は、ダンプ コンテキストの深さを 1 以上に設定する必要があります。

CMap オブジェクトが削除されたとき、またはその要素が削除されると、キーと値の両方が削除されます。

マップ クラスの派生は、リストの派生に似ています。 特殊な目的のリスト クラスの派生の図については、 Collections に関する記事を参照してください。

継承階層

CObject

CMap

要件

ヘッダー: afxtempl.h

CMap::CMap

空のマップを構築します。

CMap(INT_PTR nBlockSize = 10);

パラメーター

nBlockSize
マップを拡張するためのメモリ割り当ての粒度を指定します。

解説

マップが大きくなると、メモリは nBlockSize エントリの単位で割り当てられます。

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

CMap::CPair

キー値と、関連付けられているオブジェクトの値を格納します。

解説

これは、クラス CMap内の入れ子になった構造体です。

構造は、次の 2 つのフィールドで構成されます。

  • key キー型の実際の値。

  • value 関連付けられているオブジェクトの値。

これは、 CMap::PLookupCMap::PGetFirstAssoc、および CMap::PGetNextAssocからの戻り値を格納するために使用されます。

使用例については、 CMap::PLookupの例を参照してください。

CMap::GetCount

マップ内の要素の数を取得します。

INT_PTR GetCount() const;

戻り値

要素の数。

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

CMap::GetHashTableSize

マップのハッシュ テーブル内の要素の数を決定します。

UINT GetHashTableSize() const;

戻り値

ハッシュ テーブル内の要素の数。

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

UINT uTableSize = myMap.GetHashTableSize();

CMap::GetNextAssoc

rNextPositionで map 要素を取得し、マップ内の次の要素を参照するようにrNextPosition更新します。

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

パラメーター

rNextPosition
前のGetNextAssocまたはGetStartPosition呼び出しによって返されるPOSITION値への参照を指定します。

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

rKey
取得した要素の返されるキーを指定します。

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

rValue
取得した要素の戻り値を指定します。

解説

この関数は、マップ内のすべての要素を反復処理する場合に最も便利です。 位置シーケンスは必ずしもキー値シーケンスと同じではないことに注意してください。

取得した要素がマップの最後の要素である場合、 rNextPosition の新しい値は NULLに設定されます。

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

CMap::GetSize

マップ要素の数を返します。

INT_PTR GetSize() const;

戻り値

マップ内の項目の数。

解説

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

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

GetNextAssoc呼び出しに渡すことができるPOSITION値を返すことによって、マップの反復処理を開始します。

POSITION GetStartPosition() const;

戻り値

マップを反復処理するための開始位置を示す POSITION 値。マップが空の場合は NULL

解説

反復シーケンスは予測できません。そのため、"マップ内の最初の要素" には特別な意味はありません。

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

CMap::InitHashTable

ハッシュ テーブルを初期化します。

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

パラメーター

hashSize
ハッシュ テーブル内のエントリの数。

bAllocNow
TRUE場合は、初期化時にハッシュ テーブルを割り当てます。それ以外の場合は、必要に応じてテーブルが割り当てられます。

解説

パフォーマンスを最大限に高めるには、ハッシュ テーブルのサイズを素数にする必要があります。 競合を最小限に抑えるには、予想される最大データ セットのサイズを約 20% 大きくする必要があります。

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

CMap::IsEmpty

マップが空かどうかを判断します。

BOOL IsEmpty() const;

戻り値

このマップに要素が含まれている場合は 0 以外。それ以外の場合は 0。

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

CMap::Lookup

特定のキーにマップされた値を検索します。

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

パラメーター

ARG_KEY
key値の型を指定するテンプレート パラメーター。

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

VALUE
検索する値の型を指定します。

rValue
検索された値を受け取ります。

戻り値

要素が見つかった場合は 0 以外。それ以外の場合は 0。

解説

Lookup では、ハッシュ アルゴリズムを使用して、指定されたキーと正確に一致するキーを持つ map 要素をすばやく検索します。

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

SetAtメンバー関数の代わりに便利です。

VALUE& operator[](arg_key key);

パラメーター

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

ARG_KEY
キー値の型を指定するテンプレート パラメーター。

key
マップから値を取得するために使用するキー。

解説

したがって、代入ステートメント (l 値) の左側でのみ使用できます。 指定したキーを持つ map 要素がない場合は、新しい要素が作成されます。

マップにキーが見つからない可能性があるため、この演算子と同等の "右側" (r 値) はありません。 要素の取得には、 Lookup メンバー関数を使用します。

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

CMap::PGetFirstAssoc

マップ オブジェクトの最初のエントリを返します。

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

戻り値

マップ内の最初のエントリへのポインター。 CMap::CPairを参照してください。 マップにエントリが含まれている場合、値は NULL

解説

この関数を呼び出して、マップ オブジェクトの最初の要素をポインターで返します。

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

pAssocRecが指すマップ要素を取得します。

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

CPair *PGetNextAssoc(const CPair* pAssocRet);

パラメーター

pAssocRet
前の PGetNextAssoc または CMap::PGetFirstAssoc 呼び出しによって返されたマップ エントリを指します。

戻り値

マップ内の次のエントリへのポインター。 CMap::CPairを参照してください。 要素がマップの最後の要素である場合、値は NULL

解説

マップ内のすべての要素を反復処理するには、このメソッドを呼び出します。 PGetFirstAssocの呼び出しで最初の要素を取得し、PGetNextAssocを連続して呼び出してマップを反復処理します。

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

CMap::PLookup

特定のキーにマップされた値を検索します。

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

パラメーター

key
検索する要素のキー。

戻り値

キー構造へのポインター。 CMap::CPairを参照してください。 一致するものが見つからない場合、 CMap::PLookupNULLを返します。

解説

このメソッドを呼び出して、指定されたキーと完全に一致するキーを持つ map 要素を検索します。

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

グローバル ヘルパー関数 DestructElementsを呼び出して、このマップからすべての値を削除します。

void RemoveAll();

解説

マップが既に空の場合、関数は正しく機能します。

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

指定されたキーに対応するマップ エントリを検索します。キーが見つかった場合は、エントリを削除します。

BOOL RemoveKey(ARG_KEY key);

パラメーター

ARG_KEY
キーの型を指定するテンプレート パラメーター。

key
削除する要素のキー。

戻り値

エントリが見つかり、正常に削除された場合は 0 以外。それ以外の場合は 0。

解説

DestructElements ヘルパー関数は、エントリを削除するために使用されます。

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

CMap::SetAt

主な手段は、マップに要素を挿入することを意味します。

void SetAt(ARG_KEY key, ARG_VALUE newValue);

パラメーター

ARG_KEY
key パラメーターの型を指定するテンプレート パラメーター。

key
新しい要素のキーを指定します。

ARG_VALUE
newValue パラメーターの型を指定するテンプレート パラメーター。

newValue
新しい要素の値を指定します。

解説

まず、キーが検索されます。 キーが見つかった場合は、対応する値が変更されます。それ以外の場合は、新しいキーと値のペアが作成されます。

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

関連項目

MFC サンプル COLLECT
CObject クラス
階層図