CAtlArray クラス

このクラスは、配列オブジェクトを実装します。

構文

template<typename E, class ETraits = CElementTraits<E>>
class CAtlArray

パラメーター

E
配列に格納されるデータの型。

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

メンバー

メソッド

機能	説明
[追加]	要素を配列オブジェクトに追加するには、このメソッドを呼び出します。
追加	ある配列の内容を別の配列の末尾に追加するには、このメソッドを呼び出します。
AssertValid	配列オブジェクトが有効であることを確認するには、このメソッドを呼び出します。
CAtlArray	コンストラクター。
~CAtlArray	デストラクター。
コピー	ある配列の要素を別の配列にコピーするには、このメソッドを呼び出します。
FreeExtra	空の要素を配列から削除するには、このメソッドを呼び出します。
GetAt	1 つの要素を配列オブジェクトから取得するには、このメソッドを呼び出します。
GetCount	配列に格納されている要素の数を返すには、このメソッドを呼び出します。
GetData	配列内の最初の要素へのポインターを返すには、このメソッドを呼び出します。
InsertArrayAt	ある配列を別の配列に挿入するには、このメソッドを呼び出します。
InsertAt	新しい要素 (または要素の複数のコピー) を配列オブジェクトに挿入するには、このメソッドを呼び出します。
IsEmpty	配列が空かどうかをテストするには、このメソッドを呼び出します。
RemoveAll	配列オブジェクトからすべての要素を削除するには、このメソッドを呼び出します。
Removeat	1 つ以上の要素を配列から削除するには、このメソッドを呼び出します。
SetAt	配列オブジェクトの要素の値を設定するには、このメソッドを呼び出します。
SetAtGrow	配列オブジェクトの要素の値を設定し、必要に応じて配列を拡張するには、このメソッドを呼び出します。
SetCount	配列オブジェクトのサイズを設定するには、このメソッドを呼び出します。

演算子

演算子	説明
operator []	配列内の要素への参照を返すには、この演算子を呼び出します。

Typedefs

Typedef	説明
INARGTYPE	配列に要素を追加するために使用するデータ型。
OUTARGTYPE	配列から要素を取得するために使用するデータ型。

解説

CAtlArray は、ユーザー定義型の要素の配列を作成および管理するためのメソッドを提供します。 標準の C 配列に似ていますが、CAtlArray オブジェクトは必要に応じて動的に縮小および拡張できます。 配列インデックスは常に位置 0 から始まります。上限は固定することも、新しい要素が追加されるにしたがって拡張することもできます。

要素の数が少ない配列の場合、ATL クラス CSimpleArray を使用できます。

CAtlArray は、MFC の CArray クラスとの関係が深く、MFC プロジェクトで機能しますが、シリアル化はサポートされていません。

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

必要条件

ヘッダー: atlcoll.h

CAtlArray::Add

要素を配列オブジェクトに追加するには、このメソッドを呼び出します。

size_t Add(INARGTYPE element);
size_t Add();

パラメーター

element
配列に追加する要素。

戻り値

追加された要素のインデックスを返します。

解説

新しい要素が配列の末尾に追加されます。 要素が指定されない場合は、空の要素が追加されます。つまり、実際の要素が追加されたかのように配列のサイズが大きくなります。 操作が失敗すると、AtlThrow が引数 E_OUTOFMEMORY で呼び出されます。

例

// Declare an array of integers
CAtlArray<int> iArray;

iArray.Add(1);   // element 0
iArray.Add(2);   // element 1
iArray.Add();    // element 2

ATLASSERT(iArray.GetCount() == 3);   

CAtlArray::Append

ある配列の内容を別の配列の末尾に追加するには、このメソッドを呼び出します。

size_t Append(const CAtlArray<E, ETraits>& aSrc);

パラメーター

aSrc
追加する配列。

戻り値

追加された最初の要素のインデックスを返します。

解説

指定した配列内の要素が、既存の配列の末尾に追加されます。 必要に応じて、新しい要素を格納するためにメモリが割り当てられます。

配列は同じ型である必要があります。また、配列をそれ自体に追加することはできません。

デバッグ ビルドでは、CAtlArray 引数が有効な配列ではない場合、または aSrc が同一オブジェクトを参照する場合に、ATLASSERT が発生します。 リリース ビルドでは、無効な引数のために予期しない動作が発生する可能性があります。

例

// Declare two integer arrays
CAtlArray<int> iArray1,iArray2;

iArray1.Add(1);   // element 0
iArray1.Add(2);   // element 1

iArray2.Add(3);   // element 0
iArray2.Add(4);   // element 1

// Append iArray2 to iArray1
iArray1.Append(iArray2);

ATLASSERT(iArray1.GetCount() == 4);   

CAtlArray::AssertValid

配列オブジェクトが有効であることを確認するには、このメソッドを呼び出します。

void AssertValid() const;

解説

配列オブジェクトが有効でない場合、ATLASSERT がアサーションをスローします。 このメソッドは、_DEBUG が定義されている場合にのみ使用できます。

例

CAtlArray<float> fArray;
// AssertValid only exists in debug builds
#ifdef _DEBUG
fArray.AssertValid();   
#endif

CAtlArray::CAtlArray

コンストラクター。

CAtlArray() throw();

解説

配列オブジェクトを初期化します。

例

CAtlArray<int> iArray;   

CAtlArray::~CAtlArray

デストラクター。

~CAtlArray() throw();

解説

配列オブジェクトによって使用されるすべてのリソースを解放します。

CAtlArray::Copy

ある配列の要素を別の配列にコピーするには、このメソッドを呼び出します。

void Copy(const CAtlArray<E, ETraits>& aSrc);

パラメーター

aSrc
配列にコピーする要素のソース。

解説

ある配列の要素を別の配列の要素で上書きするには、このメソッドを呼び出します。 必要に応じて、新しい要素を格納するためにメモリが割り当てられます。 配列の要素をそれ自体にコピーすることはできません。

配列の既存の内容を保持する場合は、代わりに CAtlArray::Append を使用します。

デバッグ ビルドでは、既存の CAtlArray オブジェクトが有効でない場合、または aSrc が同一オブジェクトを参照する場合に、ATLASSERT が発生します。 リリース ビルドでは、無効な引数のために予期しない動作が発生する可能性があります。

Note

CAtlArray::Copy は、CAutoPtr クラスを使用して作成された要素で構成される配列をサポートしません。

例

CAtlArray<int> iArrayS, iArrayT;

iArrayS.Add(1);
iArrayS.Add(2);

iArrayT.Add(3);
iArrayT.Add(4);

iArrayT.Copy(iArrayS);

ATLASSERT(iArrayT.GetCount() == 2);
ATLASSERT(iArrayT[0] == 1);
ATLASSERT(iArrayT[1] == 2);   

CAtlArray::FreeExtra

空の要素を配列から削除するには、このメソッドを呼び出します。

void FreeExtra() throw();

解説

空の要素は削除されますが、配列のサイズと上限は変更されません。

デバッグビルドでは、CAtlArray オブジェクトが有効でない場合、または配列が最大サイズを超える場合に、ATLASSERT が発生します。

CAtlArray::GetAt

1 つの要素を配列オブジェクトから取得するには、このメソッドを呼び出します。

const E& GetAt(size_t iElement) const throw();
E& GetAt(size_t iElement) throw();

パラメーター

iElement
返す配列要素のインデックス値。

戻り値

必須の配列要素への参照を返します。

解説

デバッグ ビルドでは、iElement が配列内の要素の数を超えた場合に、ATLASSERT が発生します。 リリース ビルドでは、無効な引数のために予期しない動作が発生する可能性があります。

例

// Declare an array of integers

CAtlArray<int> iMyArray;
int element;

// Add ten elements to the array
for (int i = 0; i < 10; i++)
{
   iMyArray.Add(i);
}

// Use GetAt and SetAt to modify
// every element in the array

for (size_t i = 0; i < iMyArray.GetCount(); i++)
{
   element = iMyArray.GetAt(i);
   element *= 10;
   iMyArray.SetAt(i, element);
}   

CAtlArray::GetCount

配列に格納されている要素の数を返すには、このメソッドを呼び出します。

size_t GetCount() const throw();

戻り値

配列に格納されている要素の数を返します。

解説

配列の最初の要素は位置 0 にあるため、GetCount によって返される値は最大のインデックスよりも常に 1 大きくなります。

例

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

CAtlArray::GetData

配列内の最初の要素へのポインターを返すには、このメソッドを呼び出します。

E* GetData() throw();
const E* GetData() const throw();

戻り値

配列内の最初の要素を格納しているメモリ位置へのポインターを返します。 使用可能な要素がない場合は、NULL が返されます。

例

// Define an array of integers
CAtlArray<int> MyArray;

// Define a pointer
int* pData;

// Allocate enough space for 32 elements
// with buffer increase to be calculated
// automatically
MyArray.SetCount(32, -1);

// Set the pointer to the first element
pData = MyArray.GetData();

// Set array values directly
for (int j = 0; j < 32; j++, pData++)
{
   *pData = j * 10;   
}

CAtlArray::INARGTYPE

配列に要素を追加するために使用するデータ型。

typedef ETraits::INARGTYPE INARGTYPE;

CAtlArray::InsertArrayAt

ある配列を別の配列に挿入するには、このメソッドを呼び出します。

void InsertArrayAt(size_t iStart, const CAtlArray<E, ETraits>* paNew);

パラメーター

iStart
配列を挿入する位置のインデックス。

paNew
挿入する配列。

解説

配列 paNew の要素が、要素 iStart の位置から配列オブジェクトにコピーされます。 既存の配列要素は、上書きされないように移動されます。

デバッグ ビルドでは、CAtlArray オブジェクトが有効でない場合、または paNew ポインターが NULL か無効の場合に、ATLASSERT が発生します。

Note

CAtlArray::InsertArrayAt は、CAutoPtr クラスを使用して作成された要素で構成される配列をサポートしません。

例

// Define two integer arrays
CAtlArray<int> iTargetArray, iSourceArray;

// Add elements to first array
for (int x = 0; x < 10; x++)
{
   iTargetArray.Add(x);
}

// Add elements to the second array
for (int x = 0; x < 10; x++)
{
   iSourceArray.Add(x * 10);
}

// Insert the Source array into the Target
// array, starting at the 5th element.
iTargetArray.InsertArrayAt(5, &iSourceArray);   

CAtlArray::InsertAt

新しい要素 (または要素の複数のコピー) を配列オブジェクトに挿入するには、このメソッドを呼び出します。

void InsertAt(size_t iElement, INARGTYPE element, size_t nCount = 1);

パラメーター

iElement
要素 (1 つまたは複数) を挿入するインデックス。

element
挿入する要素 (1 つまたは複数) の値。

nCount
追加する要素の数。

解説

インデックス iElement の位置から、配列に 1 つ以上の要素を挿入します。 既存の要素は、上書きされないように移動されます。

デバッグ ビルドでは、CAtlArray オブジェクトが無効な場合、追加する要素数がゼロの場合、または要素の合計数が多すぎて配列に格納できない場合に、ATLASSERT が発生します。 製品版ビルドでは、無効なパラメーターを渡すと、予期しない結果が発生する可能性があります。

例

// Declare an array of integers
CAtlArray<int> iBuffer;

// Add elements to the array
for (int b = 0; b < 10; b++)
{
   iBuffer.Add(0);
}

// Instert ten 1's into the array
// at position 5
iBuffer.InsertAt(5, 1, 10);   

CAtlArray::IsEmpty

配列が空かどうかをテストするには、このメソッドを呼び出します。

bool IsEmpty() const throw();

戻り値

配列が空の場合は true、それ以外の場合は false を返します。

解説

配列に要素が含まれていない場合、配列は空であると見なされます。 したがって、配列に空の要素が含まれている場合、配列は空ではありません。

例

// Define an array of chars
CAtlArray<char> cArray;

// Add an element
cArray.Add('a');

// Confirm array is not empty
ATLASSERT(!cArray.IsEmpty());

// Remove all elements
cArray.RemoveAll();

// Confirm array is empty
ATLASSERT(cArray.IsEmpty());   

CAtlArray::operator []

配列内の要素への参照を返すには、この演算子を呼び出します。

E& operator[](size_t ielement) throw();
const E& operator[](size_t ielement) const throw();

パラメーター

iElement
返す配列要素のインデックス値。

戻り値

必須の配列要素への参照を返します。

解説

CAtlArray::GetAt と似ている関数を実行します。 この演算子は、MFC クラス CArray とは異なり、CAtlArray::SetAt の代わりに使用することはできません。

デバッグ ビルドでは、iElement が配列内の要素の合計数を超えた場合に、ATLASSERT が発生します。 製品版ビルドでは、無効なパラメーターのために、予期しない結果が発生する可能性があります。

CAtlArray::OUTARGTYPE

配列から要素を取得するために使用するデータ型。

typedef ETraits::OUTARGTYPE OUTARGTYPE;

CAtlArray::RemoveAll

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

void RemoveAll() throw();

解説

配列オブジェクトからすべての要素を削除します。

このメソッドは、CAtlArray::SetCount を呼び出して配列のサイズを変更し、その後、割り当てられたメモリを解放します。

例

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

CAtlArray::RemoveAt

1 つ以上の要素を配列から削除するには、このメソッドを呼び出します。

void RemoveAt(size_t iElement, size_t nCount = 1);

パラメーター

iElement
削除する最初の要素のインデックス。

nCount
削除する要素の数を指定します。

解説

配列から 1 つ以上の要素を削除します。 残りの要素は下方に移動されます。 上限はデクリメントされますが、CAtlArray::FreeExtra への呼び出しが行われるまでメモリは解放されません。

デバッグ ビルドでは、CAtlArray オブジェクトが有効でない場合、または iElement と nCount を組み合わせた合計が配列の要素の合計数を超えた場合に、ATLASSERT が発生します。 製品版ビルドでは、無効なパラメーターのために、予期しない結果が発生する可能性があります。

例

// Declare an array of chars
CAtlArray<char> cMyArray;

// Add ten elements to the array
for (int a = 0; a < 10; a++)
{
   cMyArray.Add('*');
}

// Remove five elements starting with
// the element at position 1
cMyArray.RemoveAt(1, 5);

// Free memory
cMyArray.FreeExtra();

// Confirm size of array
ATLASSERT(cMyArray.GetCount() == 5);   

CAtlArray::SetAt

配列オブジェクトの要素の値を設定するには、このメソッドを呼び出します。

void SetAt(size_t iElement, INARGTYPE element);

パラメーター

iElement
設定する配列要素を指定するインデックス。

element
指定した要素の新しい値。

解説

デバッグ ビルドでは、iElement が配列内の要素の数を超えた場合に、ATLASSERT が発生します。 製品版ビルドでは、無効なパラメーターのために、予期しない結果が発生する可能性があります。

例

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

CAtlArray::SetCount

配列オブジェクトのサイズを設定するには、このメソッドを呼び出します。

bool SetCount(size_t nNewSize, int nGrowBy = - 1);

パラメーター

nNewSize
配列の必要なサイズ。

nGrowBy
作成するバッファーの大きさを決定するために使用する値。 値 -1 を指定すると、内部で計算された値が使用されます。

戻り値

配列のサイズが正常に変更された場合は true、それ以外の場合は false を返します。

解説

配列のサイズは増減できます。 増やすと、余分な空の要素が配列に追加されます。 減らすと、インデックスが最も大きい要素が削除され、メモリが解放されます。

配列を使用する前にサイズを設定するには、このメソッドを使用します。 SetCount を使用しないと、要素を追加するプロセス (およびその後に実行されるメモリ割り当て) によって、パフォーマンスが低下し、メモリが断片化されます。

例

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

CAtlArray::SetAtGrow

配列オブジェクトの要素の値を設定し、必要に応じて配列を拡張するには、このメソッドを呼び出します。

void SetAtGrow(size_t iElement, INARGTYPE element);

パラメーター

iElement
設定する配列要素を指定するインデックス。

element
指定した要素の新しい値。

解説

インデックスが指す要素の値を置き換えます。 iElement が配列の現在のサイズよりも大きい場合、CAtlArray::SetCount への呼び出しを使用して、配列が自動的に拡張されます。 デバッグ ビルドでは、CAtlArray オブジェクトが有効でない場合に ATLASSERT が発生します。 製品版ビルドでは、無効なパラメーターのために、予期しない結果が発生する可能性があります。

例

// Declare an array of integers
CAtlArray<int> iGrowArray;

// Add an element
iGrowArray.Add(0);

// Add an extra element at position 19.
// This will grow the array to accommodate.
iGrowArray.SetAtGrow(19, 0);

// Confirm size of new array
ATLASSERT(iGrowArray.GetCount() == 20);

// Note: the values at position 1 to 18
// are undefined.

関連項目

MMXSwarm サンプル
DynamicConsumer サンプル
UpdatePV サンプル
マーキー サンプル
CArray クラス
クラスの概要