`CMap` クラス

[アーティクル]
06/16/2023

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

構文

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::PLookup、 CMap::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::PLookup は NULLを返します。

解説

このメソッドを呼び出して、指定されたキーと完全に一致するキーを持つ 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);
}

次の方法で共有

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

パラメーター

解説

例

関連項目

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