`CArray` Kelas

Artikel
06/16/2023

Mendukung array yang seperti array C, tetapi dapat secara dinamis mengurangi dan tumbuh seperlunya.

Sintaks

template <class TYPE, class ARG_TYPE = const TYPE&>
class CArray : public CObject

Parameter

TYPE
Parameter templat yang menentukan jenis objek yang disimpan dalam array. TYPE adalah parameter yang dikembalikan oleh CArray.

ARG_TYPE
Parameter templat yang menentukan jenis argumen yang digunakan untuk mengakses objek yang disimpan dalam array. Seringkali referensi ke TYPE. ARG_TYPE adalah parameter yang diteruskan ke CArray.

Anggota

Konstruktor Publik

Nama	Deskripsi
`CArray::CArray`	Membuat array kosong.

Metode Publik

Nama	Deskripsi
`CArray::Add`	Menambahkan elemen ke akhir array; menumbuhkan array jika perlu.
`CArray::Append`	Menambahkan array lain ke array; menumbuhkan array jika perlu
`CArray::Copy`	Menyalin array lain ke array; menumbuhkan array jika perlu.
`CArray::ElementAt`	Mengembalikan referensi sementara ke penunjuk elemen dalam array.
`CArray::FreeExtra`	Membebaskan semua memori yang tidak digunakan di atas batas atas saat ini.
`CArray::GetAt`	Mengembalikan nilai pada indeks tertentu.
`CArray::GetCount`	Mendapatkan jumlah elemen dalam array ini.
`CArray::GetData`	Memungkinkan akses ke elemen dalam array. Bisa jadi `NULL`.
`CArray::GetSize`	Mendapatkan jumlah elemen dalam array ini.
`CArray::GetUpperBound`	Mengembalikan indeks valid terbesar.
`CArray::InsertAt`	Menyisipkan elemen (atau semua elemen dalam array lain) pada indeks tertentu.
`CArray::IsEmpty`	Menentukan apakah array kosong.
`CArray::RemoveAll`	Menghapus semua elemen dari array ini.
`CArray::RemoveAt`	Menghapus elemen pada indeks tertentu.
`CArray::SetAt`	Mengatur nilai untuk indeks tertentu; array tidak diizinkan untuk tumbuh.
`CArray::SetAtGrow`	Mengatur nilai untuk indeks tertentu; menumbuhkan array jika perlu.
`CArray::SetSize`	Mengatur jumlah elemen yang akan dimuat dalam array ini.

Operator Publik

Nama	Deskripsi
`operator[]`	Mengatur atau mendapatkan elemen pada indeks yang ditentukan.

Keterangan

Indeks array selalu dimulai pada posisi 0. Anda dapat memutuskan apakah akan memperbaiki batas atas atau mengaktifkan array untuk diperluas saat Anda menambahkan elemen melewati batas saat ini. Memori dialokasikan secara berdekatan dengan batas atas, bahkan jika beberapa elemen null.

Catatan

Sebagian besar metode yang mengubah ukuran CArray objek atau menambahkan elemen ke dalamnya digunakan memcpy_s untuk memindahkan elemen. Ini adalah masalah karena memcpy_s tidak kompatibel dengan objek apa pun yang mengharuskan konstruktor dipanggil. Jika item dalam CArray tidak kompatibel dengan memcpy_s, Anda harus membuat baru CArray dengan ukuran yang sesuai. Anda kemudian harus menggunakan CArray::Copy dan CArray::SetAt untuk mengisi array baru karena metode tersebut menggunakan operator penugasan alih-alih memcpy_s.

Seperti halnya array C, waktu akses untuk CArray elemen terindeks konstan dan tidak bergantung pada ukuran array.

Tip

Sebelum menggunakan array, gunakan SetSize untuk menetapkan ukurannya dan mengalokasikan memori untuk array tersebut. Jika Anda tidak menggunakan SetSize, menambahkan elemen ke array Anda menyebabkannya sering direalokasi dan disalin. Realokasi dan penyalinan yang sering tidak efisien dan dapat memfragmentasi memori.

Jika Anda memerlukan cadangan elemen individual dalam array, Anda harus mengatur kedalaman CDumpContext objek ke 1 atau lebih besar.

Fungsi anggota tertentu dari kelas ini memanggil fungsi pembantu global yang harus disesuaikan untuk sebagian besar penggunaan CArray kelas. Lihat topik Pembantu Kelas Koleksi di bagian Makro dan Global MFC.

Derivasi kelas array seperti derivasi daftar.

Untuk informasi selengkapnya tentang cara menggunakan CArray, lihat artikel Koleksi.

Hierarki Warisan

CObject

CArray

Persyaratan

Header: afxtempl.h

`CArray::Add`

Menambahkan elemen baru ke akhir array, menumbuhkan array sebesar 1.

INT_PTR Add(ARG_TYPE newElement);

Parameter

ARG_TYPE
Parameter templat yang menentukan jenis elemen referensi argumen dalam array ini.

newElement
Elemen yang akan ditambahkan ke array ini.

Tampilkan Nilai

Indeks elemen yang ditambahkan.

Keterangan

Jika SetSize telah digunakan dengan nilai yang nGrowBy lebih besar dari 1, maka memori tambahan dapat dialokasikan. Namun, batas atas hanya akan meningkat 1.

Contoh

// example for CArray::Add
CArray<CPoint, CPoint> ptArray;

CPoint pt(10, 20);
ptArray.Add(pt);             // Element 0
ptArray.Add(CPoint(30, 40)); // Element 1

`CArray::Append`

Panggil fungsi anggota ini untuk menambahkan konten satu array ke ujung array lainnya.

INT_PTR Append(const CArray& src);

Parameter

src
Sumber elemen yang akan ditambahkan ke array.

Tampilkan Nilai

Indeks elemen pertama yang ditambahkan.

Keterangan

Array harus berjenis yang sama.

Jika perlu, Append dapat mengalokasikan memori tambahan untuk mengakomodasi elemen yang ditambahkan ke array.

Contoh

CArray<CPoint, CPoint> myArray1, myArray2;

// Add elements to the second array.
myArray2.Add(CPoint(11, 22));
myArray2.Add(CPoint(12, 42));

// Add elements to the first array and also append the second array.
myArray1.Add(CPoint(1, 2));
myArray1.Append(myArray2);

`CArray::CArray`

Membuat array kosong.

CArray();

Keterangan

Array menumbuhkan satu elemen pada satu waktu.

Contoh

CArray<CPoint, CPoint> ptArray;

`CArray::Copy`

Gunakan fungsi anggota ini untuk menyalin elemen dari satu array ke array lainnya.

void Copy(const CArray& src);

Parameter

src
Sumber elemen yang akan disalin ke array.

Keterangan

Panggil fungsi anggota ini untuk menimpa elemen satu array dengan elemen array lain.

Copy tidak membebaskan memori; namun, jika perlu, Copy dapat mengalokasikan memori tambahan untuk mengakomodasi elemen yang disalin ke array.

Contoh

CArray<CPoint, CPoint> myArray1, myArray2;

// Add elements to the second array.
myArray2.Add(CPoint(11, 22));
myArray2.Add(CPoint(12, 42));

// Copy the elements from the second array to the first.
myArray1.Copy(myArray2);

`CArray::ElementAt`

Mengembalikan referensi sementara ke elemen yang ditentukan dalam array.

TYPE& ElementAt(INT_PTR nIndex);
const TYPE& ElementAt(INT_PTR nIndex) const;

Parameter

nIndex
Indeks bilangan bulat yang lebih besar dari atau sama dengan 0 dan kurang dari atau sama dengan nilai yang dikembalikan oleh GetUpperBound.

Tampilkan Nilai

Referensi ke elemen array.

Keterangan

Ini digunakan untuk mengimplementasikan operator penugasan sisi kiri untuk array.

Contoh

Lihat contoh untuk GetSize.

`CArray::FreeExtra`

Membebaskan memori tambahan yang dialokasikan saat array tumbuh.

void FreeExtra();

Keterangan

Fungsi ini tidak berpengaruh pada ukuran atau batas atas array.

Contoh

Lihat contoh untuk GetData.

`CArray::GetAt`

Mengembalikan elemen array pada indeks yang ditentukan.

TYPE& GetAt(INT_PTR nIndex);
const TYPE& GetAt(INT_PTR nIndex) const;

Parameter

TYPE
Parameter templat yang menentukan jenis elemen array.

nIndex
Indeks bilangan bulat yang lebih besar dari atau sama dengan 0 dan kurang dari atau sama dengan nilai yang dikembalikan oleh GetUpperBound.

Tampilkan Nilai

Elemen array saat ini pada indeks ini.

Keterangan

Meneruskan nilai negatif atau nilai yang lebih besar dari nilai yang dikembalikan oleh GetUpperBound akan mengakibatkan pernyataan gagal.

Contoh

CArray<CPoint, CPoint> myArray;
CPoint pt;

// Add elements to the array.
for (int i = 0; i < 10; i++)
{
   myArray.Add(CPoint(i, 2 * i));
}

// Modify all the points in the array.
for (int i = 0; i <= myArray.GetUpperBound(); i++)
{
   pt = myArray.GetAt(i);
   pt.x = 0;
   myArray.SetAt(i, pt);
}

`CArray::GetCount`

Mengembalikan jumlah elemen array.

INT_PTR GetCount() const;

Tampilkan Nilai

Jumlah item dalam array.

Keterangan

Panggil metode ini untuk mengambil jumlah elemen dalam array. Karena indeks berbasis nol, ukurannya 1 lebih besar dari indeks terbesar. Memanggil metode ini akan menghasilkan hasil yang sama dengan CArray::GetSize metode .

Contoh

CArray<CPoint, CPoint> myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
   myArray.Add(CPoint(i, 2 * i));

// Modify all the points in the array.
for (int i = 0; i < myArray.GetCount(); i++)
{
   CPoint &pt = myArray.ElementAt(i);
   pt.x = 0;
}

`CArray::GetData`

Gunakan fungsi anggota ini untuk mendapatkan akses langsung ke elemen dalam array.

const TYPE* GetData() const;
TYPE* GetData();

Parameter

TYPE
Parameter templat yang menentukan jenis elemen array.

Tampilkan Nilai

Penunjuk ke elemen array.

Keterangan

Jika tidak ada elemen yang tersedia, GetData mengembalikan nilai null.

Meskipun akses langsung ke elemen array dapat membantu Anda bekerja lebih cepat, berhati-hatilah saat memanggil GetData; kesalahan apa pun yang Anda buat secara langsung memengaruhi elemen array Anda.

Contoh

CArray<CPoint, CPoint> myArray;

// Allocate memory for at least 32 elements.
myArray.SetSize(32, 128);

// Add elements to the array.
CPoint *pPt = (CPoint *)myArray.GetData();
for (int i = 0; i < 32; i++, pPt++)
{
   *pPt = CPoint(i, 2 * i);
}

// Only keep first 5 elements and free extra (unused) bytes.
myArray.SetSize(5, 128);
myArray.FreeExtra();

#if _DEBUG
afxDump.SetDepth(1);
afxDump << "myArray: " << &myArray << "\n";
#endif

`CArray::GetSize`

Mengembalikan ukuran array.

INT_PTR GetSize() const;

Keterangan

Karena indeks berbasis nol, ukurannya 1 lebih besar dari indeks terbesar. Memanggil metode ini akan menghasilkan hasil yang sama dengan CArray::GetCount metode .

Contoh

CArray<CPoint, CPoint> myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
   myArray.Add(CPoint(i, 2 * i));

// Modify all the points in the array.
for (int i = 0; i < myArray.GetSize(); i++)
{
   CPoint &pt = myArray.ElementAt(i);
   pt.x = 0;
}

`CArray::GetUpperBound`

Mengembalikan batas atas array ini saat ini.

INT_PTR GetUpperBound() const;

Keterangan

Karena indeks array berbasis nol, fungsi ini mengembalikan nilai 1 kurang dari GetSize.

Kondisi GetUpperBound( ) = -1 menunjukkan bahwa array tidak berisi elemen.

Contoh

Lihat contoh untuk CArray::GetAt.

`CArray::InsertAt`

Versi InsertAt pertama menyisipkan satu elemen (atau beberapa salinan elemen) pada indeks tertentu dalam array.

void InsertAt(
    INT_PTR nIndex,
    ARG_TYPE newElement,
    INT_PTR nCount = 1);

void InsertAt(
    INT_PTR nStartIndex,
    CArray* pNewArray);

Parameter

nIndex
Indeks bilangan bulat yang mungkin lebih besar dari nilai yang dikembalikan oleh GetUpperBound.

ARG_TYPE
Parameter templat yang menentukan jenis elemen dalam array ini.

newElement
Elemen yang akan ditempatkan dalam array ini.

nCount
Frekuensi elemen ini harus disisipkan (default ke 1).

nStartIndex
Indeks bilangan bulat yang mungkin lebih besar dari nilai yang dikembalikan oleh GetUpperBound.

pNewArray
Array lain yang berisi elemen yang akan ditambahkan ke array ini.

Keterangan

Dalam prosesnya, ia bergeser ke atas (dengan meningkatkan indeks) elemen yang ada pada indeks ini, dan menggeser semua elemen di atasnya.

Versi kedua menyisipkan semua elemen dari koleksi lain CArray , dimulai dari nStartIndex posisi.

Fungsi ini SetAt , sebaliknya, menggantikan satu elemen array yang ditentukan dan tidak menggeser elemen apa pun.

Contoh

// example for CArray::InsertAt

CArray<CPoint, CPoint> ptArray;

ptArray.Add(CPoint(10, 20));         // Element 0
ptArray.Add(CPoint(30, 40));         // Element 1 (will become element 2)
ptArray.InsertAt(1, CPoint(50, 60)); // New element 1

`CArray::IsEmpty`

Menentukan apakah array kosong.

BOOL IsEmpty() const;

Tampilkan Nilai

Bukan nol jika array tidak berisi elemen; jika tidak, 0.

`CArray::operator []`

Operator subskrip ini adalah pengganti SetAt fungsi dan GetAt yang nyaman.

TYPE& operator[](int_ptr nindex);
const TYPE& operator[](int_ptr nindex) const;

Parameter

TYPE
Parameter templat yang menentukan jenis elemen dalam array ini.

nIndex
Indeks elemen yang akan diakses.

Keterangan

Operator pertama, yang dipanggil untuk array yang bukan const, dapat digunakan di kanan (r-value) atau kiri (nilai l) dari pernyataan penugasan. Yang kedua, yang dipanggil untuk const array, hanya dapat digunakan di sebelah kanan.

Versi Debug pustaka menegaskan jika subskrip (baik di sisi kiri atau kanan pernyataan penugasan) berada di luar batas.

Contoh

CArray<CPoint, CPoint> myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
{
   myArray.Add(CPoint(i, 2 * i));
}

// Modify all the points in the array.
for (int i = 0; i <= myArray.GetUpperBound(); i++)
{
   myArray[i].x = 0;
}

`CArray::RelocateElements`

Merelokasi data ke buffer baru saat array harus tumbuh atau menyusut.

template<class TYPE, class ARG_TYPE>
AFX_INLINE void CArray<TYPE, ARG_TYPE>::RelocateElements(
    TYPE* pNewData,
    const TYPE* pData,
    INT_PTR nCount);

Parameter

pNewData
Buffer baru untuk array elemen.

pData
Array elemen lama.

nCount
Jumlah elemen dalam array lama.

Keterangan

pNewData selalu cukup besar untuk menampung semua pData elemen.

Implementasi CArray menggunakan metode ini untuk menyalin data lama ke buffer baru ketika array harus tumbuh atau menyusut (ketika SetSize atau FreeExtra dipanggil). Implementasi default hanya menyalin data.

Untuk array di mana elemen berisi penunjuk ke salah satu anggotanya sendiri, atau struktur lain berisi penunjuk ke salah satu elemen array, pointer tidak diperbarui dalam salinan biasa. Dalam hal ini, Anda dapat memperbaiki pointer dengan menerapkan spesialisasi RelocateElements dengan jenis yang relevan. Anda juga bertanggung jawab atas penyalinan data.

`CArray::RemoveAll`

Menghapus semua elemen dari array ini.

void RemoveAll();

Keterangan

Jika array sudah kosong, fungsi masih berfungsi.

Contoh

CArray<CPoint, CPoint> myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
   myArray.Add(CPoint(i, 2 * i));

myArray.RemoveAll();

#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << "myArray: " << &myArray << "\n";
#endif

`CArray::RemoveAt`

Menghapus satu atau beberapa elemen yang dimulai pada indeks tertentu dalam array.

void RemoveAt(
    INT_PTR nIndex,
    INT_PTR nCount = 1);

Parameter

nIndex
Indeks bilangan bulat yang lebih besar dari atau sama dengan 0 dan kurang dari atau sama dengan nilai yang dikembalikan oleh GetUpperBound.

nCount
Jumlah elemen yang akan dihapus.

Keterangan

Dalam prosesnya, ia menggeser ke bawah semua elemen di atas elemen yang dihapus. Ini mengurangi batas atas array tetapi tidak membebaskan memori.

Jika Anda mencoba menghapus lebih banyak elemen daripada yang terkandung dalam array di atas titik penghapusan, maka versi Debug pustaka menegaskan.

Contoh

CArray<CPoint, CPoint> myArray;

// Add elements to the array.
for (int i = 0; i < 10; i++)
{
   myArray.Add(CPoint(i, 2 * i));
}

myArray.RemoveAt(5);

#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << "myArray: " << &myArray << "\n";
#endif

`CArray::SetAt`

Mengatur elemen array pada indeks yang ditentukan.

void SetAt(INT_PTR nIndex, ARG_TYPE newElement);

Parameter

nIndex
Indeks bilangan bulat yang lebih besar dari atau sama dengan 0 dan kurang dari atau sama dengan nilai yang dikembalikan oleh GetUpperBound.

ARG_TYPE
Parameter templat yang menentukan jenis argumen yang digunakan untuk mereferensikan elemen array.

newElement
Nilai elemen baru yang akan disimpan pada posisi yang ditentukan.

Keterangan

SetAt tidak akan menyebabkan array tumbuh. Gunakan SetAtGrow jika Anda ingin array tumbuh secara otomatis.

Anda harus memastikan bahwa nilai indeks Anda mewakili posisi yang valid dalam array. Jika berada di luar batas, maka versi Debug pustaka menegaskan.

Contoh

Lihat contoh untuk GetAt.

`CArray::SetAtGrow`

Mengatur elemen array pada indeks yang ditentukan.

void SetAtGrow(INT_PTR nIndex, ARG_TYPE newElement);

Parameter

nIndex
Indeks bilangan bulat yang lebih besar dari atau sama dengan 0.

ARG_TYPE
Parameter templat yang menentukan jenis elemen dalam array.

newElement
Elemen yang akan ditambahkan ke array ini. Nilai NULL diperbolehkan.

Keterangan

Array tumbuh secara otomatis jika perlu (yaitu, batas atas disesuaikan untuk mengakomodasi elemen baru).

Contoh

// example for CArray::SetAtGrow
CArray<CPoint, CPoint> ptArray;

ptArray.Add(CPoint(10, 20)); // Element 0
ptArray.Add(CPoint(30, 40)); // Element 1
// Element 2 deliberately skipped
ptArray.SetAtGrow(3, CPoint(50, 60)); // Element 3

`CArray::SetSize`

Menetapkan ukuran array kosong atau yang ada; mengalokasikan memori jika perlu.

void SetSize(
    INT_PTR nNewSize,
    INT_PTR nGrowBy = -1);

Parameter

nNewSize
Ukuran array baru (jumlah elemen). Harus lebih besar dari atau sama dengan 0.

nGrowBy
Jumlah minimum slot elemen untuk dialokasikan jika peningkatan ukuran diperlukan.

Keterangan

Jika ukuran baru lebih kecil dari ukuran lama, maka array dipotong dan semua memori yang tidak digunakan dilepaskan.

Gunakan fungsi ini untuk mengatur ukuran array Anda sebelum Anda mulai menggunakan array. Jika Anda tidak menggunakan SetSize, menambahkan elemen ke array Anda menyebabkannya sering direalokasi dan disalin. Realokasi dan penyalinan yang sering tidak efisien dan dapat memfragmentasi memori.

Parameter nGrowBy memengaruhi alokasi memori internal saat array tumbuh. Penggunaannya tidak pernah memengaruhi ukuran array seperti yang dilaporkan oleh GetSize dan GetUpperBound. Jika nilai default digunakan, MFC mengalokasikan memori dengan cara yang dihitung untuk menghindari fragmentasi memori dan mengoptimalkan efisiensi untuk sebagian besar kasus.

Contoh

Lihat contoh untuk GetData.

Lihat juga

Sampel MFC COLLECT
CObject Kelas
Bagan Hierarki
CObArray Kelas
Pembantu Kelas Koleksi

Bagikan melalui

CArray Kelas

Sintaks

Parameter

Anggota

Konstruktor Publik

Metode Publik

Operator Publik

Keterangan

Hierarki Warisan

Persyaratan

CArray::Add

Parameter

Tampilkan Nilai

Keterangan

Contoh

CArray::Append

Parameter

Tampilkan Nilai

Keterangan

Contoh

CArray::CArray

Keterangan

Contoh

CArray::Copy

Parameter

Keterangan

Contoh

CArray::ElementAt

Parameter

Tampilkan Nilai

Keterangan

Contoh

CArray::FreeExtra

Keterangan

Contoh

CArray::GetAt

Parameter

Tampilkan Nilai

Keterangan

Contoh

CArray::GetCount

Tampilkan Nilai

Keterangan

Contoh

CArray::GetData

Parameter

Tampilkan Nilai

Keterangan

Contoh

CArray::GetSize

Keterangan

Contoh

CArray::GetUpperBound

Keterangan

Contoh

CArray::InsertAt

Parameter

Keterangan

Contoh

CArray::IsEmpty

Tampilkan Nilai

CArray::operator []

Parameter

Keterangan

Contoh

CArray::RelocateElements

Parameter

Keterangan

CArray::RemoveAll

Keterangan

Contoh

CArray::RemoveAt

Parameter

Keterangan

Contoh

CArray::SetAt

Parameter

Keterangan

Contoh

`CArray` Kelas

`CArray::Add`

`CArray::Append`

`CArray::CArray`

`CArray::Copy`

`CArray::ElementAt`

`CArray::FreeExtra`

`CArray::GetAt`

`CArray::GetCount`

`CArray::GetData`

`CArray::GetSize`

`CArray::GetUpperBound`

`CArray::InsertAt`

`CArray::IsEmpty`

`CArray::operator []`

`CArray::RelocateElements`

`CArray::RemoveAll`

`CArray::RemoveAt`

`CArray::SetAt`

`CArray::SetAtGrow`

`CArray::SetSize`