Kelas CAtlArray

Artikel
06/16/2023

Kelas ini mengimplementasikan objek array.

Sintaks

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

Parameter

E
Jenis data yang akan disimpan dalam array.

ETraits
Kode yang digunakan untuk menyalin atau memindahkan elemen.

Anggota

Metode

Fungsi	Deskripsi
Tambahkan	Panggil metode ini untuk menambahkan elemen ke objek array.
Tambah	Panggil metode ini untuk menambahkan konten satu array ke ujung array lainnya.
AssertValid	Panggil metode ini untuk mengonfirmasi bahwa objek array valid.
CAtlArray	Konstruktor.
~CAtlArray	Destruktor.
Menyalin	Panggil metode ini untuk menyalin elemen dari satu array ke array lainnya.
FreeExtra	Panggil metode ini untuk menghapus elemen kosong apa pun dari array.
GetAt	Panggil metode ini untuk mengambil satu elemen dari objek array.
GetCount	Panggil metode ini untuk mengembalikan jumlah elemen yang disimpan dalam array.
GetData	Panggil metode ini untuk mengembalikan penunjuk ke elemen pertama dalam array.
InsertArrayAt	Panggil metode ini untuk menyisipkan satu array ke array lainnya.
SisipkanAt	Panggil metode ini untuk menyisipkan elemen baru (atau beberapa salinan elemen) ke dalam objek array.
IsEmpty	Panggil metode ini untuk menguji apakah array kosong.
HapusSemua	Panggil metode ini untuk menghapus semua elemen dari objek array.
HapusAt	Panggil metode ini untuk menghapus satu atau beberapa elemen dari array.
SetAt	Panggil metode ini untuk mengatur nilai elemen dalam objek array.
SetAtGrow	Panggil metode ini untuk mengatur nilai elemen dalam objek array, memperluas array sesuai kebutuhan.
SetCount	Panggil metode ini untuk mengatur ukuran objek array.

Operator

Operator	Deskripsi
`operator []`	Panggil operator ini untuk mengembalikan referensi ke elemen dalam array.

Typedefs

Typedef	Deskripsi
INARGTYPE	Jenis data yang digunakan untuk menambahkan elemen ke array.
OUTARGTYPE	Jenis data yang digunakan untuk mengambil elemen dari array.

Keterangan

CAtlArray menyediakan metode untuk membuat dan mengelola array elemen dari jenis yang ditentukan pengguna. Meskipun mirip dengan array C standar, CAtlArray objek dapat menyusut dan tumbuh secara dinamis seperlunya. Indeks array selalu dimulai pada posisi 0, dan batas atas dapat diperbaiki, atau diizinkan untuk memperluas saat elemen baru ditambahkan.

Untuk array dengan sejumlah kecil elemen, CSimpleArray kelas ATL dapat digunakan.

CAtlArray terkait erat dengan kelas MFC CArray dan akan bekerja dalam proyek MFC, meskipun tanpa dukungan serialisasi.

Untuk informasi selengkapnya, lihat Kelas Koleksi ATL.

Persyaratan

Header: atlcoll.h

CAtlArray::Tambahkan

Panggil metode ini untuk menambahkan elemen ke objek array.

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

Parameter

elemen
Elemen yang akan ditambahkan ke array.

Tampilkan Nilai

Mengembalikan indeks elemen yang ditambahkan.

Keterangan

Elemen baru ditambahkan ke akhir array. Jika tidak ada elemen yang disediakan, elemen kosong ditambahkan; artinya, array ditingkatkan ukurannya seolah-olah elemen nyata telah ditambahkan. Jika operasi gagal, AtlThrow dipanggil dengan argumen E_OUTOFMEMORY.

Contoh

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

Panggil metode ini untuk menambahkan konten satu array ke ujung array lainnya.

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

Parameter

aSrc
Array yang akan ditambahkan.

Tampilkan Nilai

Mengembalikan indeks elemen pertama yang ditambahkan.

Keterangan

Elemen dalam array yang disediakan ditambahkan ke akhir array yang ada. Jika perlu, memori akan dialokasikan untuk mengakomodasi elemen baru.

Array harus dari jenis yang sama, dan tidak dimungkinkan untuk menambahkan array ke dirinya sendiri.

Dalam build debug, ATLASSERT akan dinaikkan jika CAtlArray argumen bukan array yang valid atau jika aSrc mengacu pada objek yang sama. Dalam build rilis, argumen yang tidak valid dapat menyebabkan perilaku yang tidak dapat diprediksi.

Contoh

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

Panggil metode ini untuk mengonfirmasi bahwa objek array valid.

void AssertValid() const;

Keterangan

Jika objek array tidak valid, ATLASSERT akan memberikan pernyataan. Metode ini hanya tersedia jika _DEBUG ditentukan.

Contoh

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

CAtlArray::CAtlArray

Konstruktor.

CAtlArray() throw();

Keterangan

Menginisialisasi objek array.

Contoh

CAtlArray<int> iArray;

CAtlArray::~CAtlArray

Destruktor.

~CAtlArray() throw();

Keterangan

Mengosongkan sumber daya apa pun yang digunakan oleh objek array.

CAtlArray::Copy

Panggil metode ini untuk menyalin elemen dari satu array ke array lainnya.

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

Parameter

aSrc
Sumber elemen untuk disalin ke array.

Keterangan

Panggil metode ini untuk menimpa elemen dari satu array dengan elemen array lain. Jika perlu, memori akan dialokasikan untuk mengakomodasi elemen baru. Tidak dimungkinkan untuk menyalin elemen array ke dirinya sendiri.

Jika konten array yang ada harus dipertahankan, gunakan CAtlArray::Tambahkan sebagai gantinya.

Dalam build debug, ATLASSERT akan dinaikkan jika objek yang ada CAtlArray tidak valid, atau jika aSrc mengacu pada objek yang sama. Dalam build rilis, argumen yang tidak valid dapat menyebabkan perilaku yang tidak dapat diprediksi.

Catatan

CAtlArray::Copy tidak mendukung array yang terdiri dari elemen yang dibuat dengan kelas CAutoPtr .

Contoh

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

Panggil metode ini untuk menghapus elemen kosong apa pun dari array.

void FreeExtra() throw();

Keterangan

Elemen kosong apa pun dihapus, tetapi ukuran dan batas atas array tetap tidak berubah.

Dalam build debug, ATLASSERT akan dinaikkan jika objek CAtlArray tidak valid, atau jika array akan melebihi ukuran maksimumnya.

CAtlArray::GetAt

Panggil metode ini untuk mengambil satu elemen dari objek array.

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

Parameter

iElement
Nilai indeks elemen array yang akan dikembalikan.

Tampilkan Nilai

Mengembalikan referensi ke elemen array yang diperlukan.

Keterangan

Dalam build debug, ATLASSERT akan dinaikkan jika iElement melebihi jumlah elemen dalam array. Dalam build rilis, argumen yang tidak valid dapat menyebabkan perilaku yang tidak dapat diprediksi.

Contoh

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

Panggil metode ini untuk mengembalikan jumlah elemen yang disimpan dalam array.

size_t GetCount() const throw();

Tampilkan Nilai

Mengembalikan jumlah elemen yang disimpan dalam array.

Keterangan

Karena elemen pertama dalam array berada di posisi 0, nilai yang dikembalikan oleh GetCount selalu 1 lebih besar dari indeks terbesar.

Contoh

Lihat contoh untuk CAtlArray::GetAt.

CAtlArray::GetData

Panggil metode ini untuk mengembalikan penunjuk ke elemen pertama dalam array.

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

Tampilkan Nilai

Mengembalikan penunjuk ke lokasi memori yang menyimpan elemen pertama dalam array. Jika tidak ada elemen yang tersedia, NULL dikembalikan.

Contoh

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

Jenis data yang digunakan untuk menambahkan elemen ke array.

typedef ETraits::INARGTYPE INARGTYPE;

CAtlArray::InsertArrayAt

Panggil metode ini untuk menyisipkan satu array ke array lainnya.

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

Parameter

iStart
Indeks tempat array akan disisipkan.

paNew
Array yang akan disisipkan.

Keterangan

Elemen dari array paNew disalin ke dalam objek array, dimulai dari elemen iStart. Elemen array yang ada dipindahkan untuk menghindari ditimpa.

Dalam build debug, ATLASSERT akan dinaikkan jika CAtlArray objek tidak valid, atau jika pointer paNew NULL atau tidak valid.

Catatan

CAtlArray::InsertArrayAt tidak mendukung array yang terdiri dari elemen yang dibuat dengan kelas CAutoPtr .

Contoh

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

Panggil metode ini untuk menyisipkan elemen baru (atau beberapa salinan elemen) ke dalam objek array.

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

Parameter

iElement
Indeks tempat elemen atau elemen akan disisipkan.

elemen
Nilai elemen atau elemen yang akan disisipkan.

nCount
Jumlah elemen yang akan ditambahkan.

Keterangan

Menyisipkan satu atau beberapa elemen ke dalam array, dimulai dari iElement indeks. Elemen yang ada dipindahkan untuk menghindari ditimpa.

Dalam build debug, ATLASSERT akan dinaikkan jika CAtlArray objek tidak valid, jumlah elemen yang akan ditambahkan adalah nol, atau jumlah gabungan elemen terlalu besar untuk dikandung array. Dalam build ritel, melewati parameter yang tidak valid dapat menyebabkan hasil yang tidak dapat diprediksi.

Contoh

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

Panggil metode ini untuk menguji apakah array kosong.

bool IsEmpty() const throw();

Tampilkan Nilai

Mengembalikan true jika array kosong, jika tidak salah.

Keterangan

Array dikatakan kosong jika tidak berisi elemen. Oleh karena itu, bahkan jika array berisi elemen kosong, itu tidak kosong.

Contoh

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

Panggil operator ini untuk mengembalikan referensi ke elemen dalam array.

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

Parameter

iElement
Nilai indeks elemen array yang akan dikembalikan.

Tampilkan Nilai

Mengembalikan referensi ke elemen array yang diperlukan.

Keterangan

Melakukan fungsi serupa dengan CAtlArray::GetAt. Tidak seperti CArray kelas MFC, operator ini tidak dapat digunakan sebagai pengganti CAtlArray::SetAt.

Dalam build debug, ATLASSERT akan dinaikkan jika iElement melebihi jumlah total elemen dalam array. Dalam build ritel, parameter yang tidak valid dapat menyebabkan hasil yang tidak dapat diprediksi.

CAtlArray::OUTARGTYPE

Jenis data yang digunakan untuk mengambil elemen dari array.

typedef ETraits::OUTARGTYPE OUTARGTYPE;

CAtlArray::RemoveAll

Panggil metode ini untuk menghapus semua elemen dari objek array.

void RemoveAll() throw();

Keterangan

Menghapus semua elemen dari objek array.

Metode ini memanggil CAtlArray::SetCount untuk mengubah ukuran array dan kemudian membebaskan memori yang dialokasikan.

Contoh

Lihat contoh untuk CAtlArray::IsEmpty.

CAtlArray::RemoveAt

Panggil metode ini untuk menghapus satu atau beberapa elemen dari array.

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

Parameter

iElement
Indeks elemen pertama yang akan dihapus.

nCount
Jumlah elemen yang akan dihapus.

Keterangan

Menghapus satu atau beberapa elemen dari array. Elemen yang tersisa digeser ke bawah. Batas atas dikurangi, tetapi memori tidak dikosongkan sampai panggilan ke CAtlArray::FreeExtra dibuat.

Dalam build debug, ATLASSERT akan dinaikkan jika CAtlArray objek tidak valid, atau jika total gabungan iElement dan nCount melebihi jumlah total elemen dalam array. Dalam build ritel, parameter yang tidak valid dapat menyebabkan hasil yang tidak dapat diprediksi.

Contoh

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

Panggil metode ini untuk mengatur nilai elemen dalam objek array.

void SetAt(size_t iElement, INARGTYPE element);

Parameter

iElement
Indeks yang menunjuk ke elemen array yang akan diatur.

elemen
Nilai baru elemen yang ditentukan.

Keterangan

Dalam build debug, ATLASSERT akan dinaikkan jika iElement melebihi jumlah elemen dalam array. Dalam build ritel, parameter yang tidak valid dapat mengakibatkan hasil yang tidak dapat diprediksi.

Contoh

Lihat contoh untuk CAtlArray::GetAt.

CAtlArray::SetCount

Panggil metode ini untuk mengatur ukuran objek array.

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

Parameter

nNewSize
Ukuran array yang diperlukan.

nGrowBy
Nilai yang digunakan untuk menentukan seberapa besar untuk membuat buffer. Nilai -1 menyebabkan nilai yang dihitung secara internal digunakan.

Tampilkan Nilai

Mengembalikan true jika array berhasil diubah ukurannya, false jika tidak.

Keterangan

Array dapat ditingkatkan atau dikurangi ukurannya. Jika ditingkatkan, elemen kosong tambahan ditambahkan ke array. Jika dikurangi, elemen dengan indeks terbesar akan dihapus dan memori dibebaskan.

Gunakan metode ini untuk mengatur ukuran array sebelum menggunakannya. Jika SetCount tidak digunakan, proses penambahan elemen — dan alokasi memori berikutnya yang dilakukan — akan mengurangi performa dan memori fragmen.

Contoh

Lihat contoh untuk CAtlArray::GetData.

CAtlArray::SetAtGrow

Panggil metode ini untuk mengatur nilai elemen dalam objek array, memperluas array sesuai kebutuhan.

void SetAtGrow(size_t iElement, INARGTYPE element);

Parameter

iElement
Indeks yang menunjuk ke elemen array yang akan diatur.

elemen
Nilai baru elemen yang ditentukan.

Keterangan

Menggantikan nilai elemen yang ditujukkan oleh indeks. Jika iElement lebih besar dari ukuran array saat ini, array secara otomatis ditingkatkan menggunakan panggilan ke CAtlArray::SetCount. Dalam build debug, ATLASSERT akan dinaikkan jika CAtlArray objek tidak valid. Dalam build ritel, parameter yang tidak valid dapat menyebabkan hasil yang tidak dapat diprediksi.

Contoh

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

Lihat juga

Sampel MMXSwarm
Sampel DynamicConsumer
Sampel UpdatePV
Sampel Marquee
Kelas CArray
Gambaran Umum Kelas

Bagikan melalui

Kelas CAtlArray

Sintaks

Parameter

Anggota

Metode

Operator

Typedefs

Keterangan

Persyaratan

CAtlArray::Tambahkan

Parameter

Tampilkan Nilai

Keterangan

Contoh

CAtlArray::Tambahkan

Parameter

Tampilkan Nilai

Keterangan

Contoh

CAtlArray::AssertValid

Keterangan

Contoh

CAtlArray::CAtlArray

Keterangan

Contoh

CAtlArray::~CAtlArray

Keterangan

CAtlArray::Copy

Parameter

Keterangan

Contoh

CAtlArray::FreeExtra

Keterangan

CAtlArray::GetAt

Parameter

Tampilkan Nilai

Keterangan

Contoh

CAtlArray::GetCount

Tampilkan Nilai

Keterangan

Contoh

CAtlArray::GetData

Tampilkan Nilai

Contoh

CAtlArray::INARGTYPE

CAtlArray::InsertArrayAt

Parameter

Keterangan

Contoh

CAtlArray::InsertAt

Parameter

Keterangan

Contoh

CAtlArray::IsEmpty

Tampilkan Nilai

Keterangan

Contoh

CAtlArray::operator []

Parameter

Tampilkan Nilai

Keterangan

CAtlArray::OUTARGTYPE

CAtlArray::RemoveAll

Keterangan

Contoh

CAtlArray::RemoveAt

Parameter

Keterangan

Contoh

CAtlArray::SetAt

Parameter

Keterangan

Contoh

CAtlArray::SetCount

Parameter

Tampilkan Nilai

Keterangan

Contoh