CAtlArray-klasse

Opmerking

De ATL (Active Template Library) wordt nog steeds ondersteund. We voegen echter geen functies meer toe of werken de documentatie bij.

Met deze klasse wordt een matrixobject geïmplementeerd.

Syntaxis

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

Parameterwaarden

E
Het type gegevens dat moet worden opgeslagen in de matrix.

ETraits
De code die wordt gebruikt om elementen te kopiëren of te verplaatsen.

Leden

Methods

Functie	Description
Add	Roep deze methode aan om een element toe te voegen aan het matrixobject.
Toevoegen	Roep deze methode aan om de inhoud van een matrix toe te voegen aan het einde van een andere matrix.
AssertValid	Roep deze methode aan om te bevestigen dat het matrixobject geldig is.
CAtlArray	De constructor.
~CAtlArray	De destructor.
Copy	Roep deze methode aan om de elementen van de ene matrix naar de andere te kopiëren.
FreeExtra	Roep deze methode aan om lege elementen uit de matrix te verwijderen.
GetAt	Roep deze methode aan om één element op te halen uit het matrixobject.
GetCount	Roep deze methode aan om het aantal elementen te retourneren dat is opgeslagen in de matrix.
GetData	Roep deze methode aan om een aanwijzer te retourneren naar het eerste element in de matrix.
InsertArrayAt	Roep deze methode aan om een matrix in te voegen in een andere.
InsertAt	Roep deze methode aan om een nieuw element (of meerdere kopieën van een element) in te voegen in het matrixobject.
IsEmpty	Roep deze methode aan om te testen of de matrix leeg is.
RemoveAll	Roep deze methode aan om alle elementen uit het matrixobject te verwijderen.
RemoveAt	Roep deze methode aan om een of meer elementen uit de matrix te verwijderen.
SetAt	Roep deze methode aan om de waarde van een element in het matrixobject in te stellen.
SetAtGrow	Roep deze methode aan om de waarde van een element in het matrixobject in te stellen, waarbij de matrix naar behoefte wordt uitgebreid.
SetCount	Roep deze methode aan om de grootte van het matrixobject in te stellen.

Bedieners

Operator	Description
operator []	Roep deze operator aan om een verwijzing naar een element in de matrix te retourneren.

Typedefs

Typedef	Description
INARGTYPE	Het gegevenstype dat moet worden gebruikt voor het toevoegen van elementen aan de matrix.
OUTARGTYPE	Het gegevenstype dat moet worden gebruikt voor het ophalen van elementen uit de matrix.

Opmerkingen

CAtlArray biedt methoden voor het maken en beheren van een matrix met elementen van een door de gebruiker gedefinieerd type. Hoewel het object vergelijkbaar is met standaard-C-matrices, kan het CAtlArray object zo nodig dynamisch verkleinen en groeien. De matrixindex begint altijd op positie 0 en de bovengrens kan worden vastgezet of mag worden uitgebreid wanneer er nieuwe elementen worden toegevoegd.

Voor matrices met een klein aantal elementen kan de ATL-klasse CSimpleArray worden gebruikt.

CAtlArray is nauw verwant aan de klasse van CArray MFC en werkt in een MFC-project, zij het zonder serialisatieondersteuning.

Zie ATL-verzamelingsklassen voor meer informatie.

Requirements

Koptekst: atlcoll.h

CAtlArray::Toevoegen

Roep deze methode aan om een element toe te voegen aan het matrixobject.

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

Parameterwaarden

element
Het element dat moet worden toegevoegd aan de matrix.

Retourwaarde

Retourneert de index van het toegevoegde element.

Opmerkingen

Het nieuwe element wordt toegevoegd aan het einde van de matrix. Als er geen element wordt opgegeven, wordt er een leeg element toegevoegd; Dat wil zeggen dat de matrix groter wordt alsof er een echt element is toegevoegd. Als de bewerking mislukt, wordt AtlThrow aangeroepen met het argument E_OUTOFMEMORY.

Example

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

Roep deze methode aan om de inhoud van een matrix toe te voegen aan het einde van een andere matrix.

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

Parameterwaarden

aSrc
De matrix die moet worden toegevoegd.

Retourwaarde

Retourneert de index van het eerste toegevoegde element.

Opmerkingen

De elementen in de opgegeven matrix worden toegevoegd aan het einde van de bestaande matrix. Indien nodig wordt geheugen toegewezen aan de nieuwe elementen.

De matrices moeten van hetzelfde type zijn en het is niet mogelijk om een matrix aan zichzelf toe te voegen.

In builds voor foutopsporing wordt een ATLASSERT gegenereerd als het CAtlArray argument geen geldige matrix is of als aSrc naar hetzelfde object verwijst. In release-builds kunnen ongeldige argumenten leiden tot onvoorspelbaar gedrag.

Example

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

Roep deze methode aan om te bevestigen dat het matrixobject geldig is.

void AssertValid() const;

Opmerkingen

Als het matrixobject ongeldig is, genereert ATLASSERT een assertie. Deze methode is alleen beschikbaar als _DEBUG is gedefinieerd.

Example

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

CAtlArray::CAtlArray

De constructor.

CAtlArray() throw();

Opmerkingen

Initialiseert het matrixobject.

Example

CAtlArray<int> iArray;   

CAtlArray::~CAtlArray

De destructor.

~CAtlArray() throw();

Opmerkingen

Maakt alle resources vrij die door het matrixobject worden gebruikt.

CAtlArray::Copy

Roep deze methode aan om de elementen van de ene matrix naar de andere te kopiëren.

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

Parameterwaarden

aSrc
De bron van de elementen die moeten worden gekopieerd naar een matrix.

Opmerkingen

Roep deze methode aan om elementen van één matrix te overschrijven met de elementen van een andere matrix. Indien nodig wordt geheugen toegewezen aan de nieuwe elementen. Het is niet mogelijk om elementen van een matrix naar zichzelf te kopiëren.

Als de bestaande inhoud van de matrix behouden moet blijven, gebruikt u in plaats daarvan CAtlArray::Append .

In builds voor foutopsporing wordt een ATLASSERT gegenereerd als het bestaande CAtlArray object niet geldig is of als aSrc naar hetzelfde object verwijst. In release-builds kunnen ongeldige argumenten leiden tot onvoorspelbaar gedrag.

Opmerking

CAtlArray::Copy biedt geen ondersteuning voor matrices die bestaan uit elementen die zijn gemaakt met de CAutoPtr-klasse .

Example

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

Roep deze methode aan om lege elementen uit de matrix te verwijderen.

void FreeExtra() throw();

Opmerkingen

Lege elementen worden verwijderd, maar de grootte en bovengrens van de matrix blijven ongewijzigd.

In builds voor foutopsporing wordt een ATLASSERT gegenereerd als het CAtlArray-object niet geldig is of als de matrix de maximale grootte overschrijdt.

CAtlArray::GetAt

Roep deze methode aan om één element op te halen uit het matrixobject.

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

Parameterwaarden

iElement
De indexwaarde van het matrixelement dat moet worden geretourneerd.

Retourwaarde

Retourneert een verwijzing naar het vereiste matrixelement.

Opmerkingen

In builds voor foutopsporing wordt een ATLASSERT gegenereerd als iElement het aantal elementen in de matrix overschrijdt. In release-builds kan een ongeldig argument leiden tot onvoorspelbaar gedrag.

Example

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

Roep deze methode aan om het aantal elementen te retourneren dat is opgeslagen in de matrix.

size_t GetCount() const throw();

Retourwaarde

Retourneert het aantal elementen dat is opgeslagen in de matrix.

Opmerkingen

Aangezien het eerste element in de matrix zich op positie 0 bevindt, is de geretourneerde GetCount waarde altijd 1 groter dan de grootste index.

Example

Zie het voorbeeld voor CAtlArray::GetAt.

CAtlArray::GetData

Roep deze methode aan om een aanwijzer te retourneren naar het eerste element in de matrix.

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

Retourwaarde

Retourneert een aanwijzer naar de geheugenlocatie waarin het eerste element in de matrix wordt opgeslagen. Als er geen elementen beschikbaar zijn, wordt NULL geretourneerd.

Example

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

Het gegevenstype dat moet worden gebruikt voor het toevoegen van elementen aan de matrix.

typedef ETraits::INARGTYPE INARGTYPE;

CAtlArray::InsertArrayAt

Roep deze methode aan om een matrix in te voegen in een andere.

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

Parameterwaarden

iStart
De index waarop de matrix moet worden ingevoegd.

paNew
De matrix die moet worden ingevoegd.

Opmerkingen

Elementen uit de matrixpaNew worden gekopieerd naar het matrixobject, beginnend bij element iStart. De bestaande matrixelementen worden verplaatst om te voorkomen dat ze worden overschreven.

In builds voor foutopsporing wordt een ATLASSERT gegenereerd als het CAtlArray object ongeldig is of als de paNew-aanwijzer NULL of ongeldig is.

Opmerking

CAtlArray::InsertArrayAt biedt geen ondersteuning voor matrices die bestaan uit elementen die zijn gemaakt met de CAutoPtr-klasse .

Example

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

Roep deze methode aan om een nieuw element (of meerdere kopieën van een element) in te voegen in het matrixobject.

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

Parameterwaarden

iElement
De index waarin het element of de elementen moeten worden ingevoegd.

element
De waarde van het element of de elementen die moeten worden ingevoegd.

nCount
Het aantal elementen dat moet worden toegevoegd.

Opmerkingen

Hiermee voegt u een of meer elementen in de matrix in, beginnend bij index iElement. Bestaande elementen worden verplaatst om te voorkomen dat ze worden overschreven.

In builds voor foutopsporing wordt een ATLASSERT gegenereerd als het CAtlArray object ongeldig is, het aantal elementen dat moet worden toegevoegd nul is of het gecombineerde aantal elementen te groot is voor de matrix die moet worden opgenomen. In retail-builds kan het doorgeven van ongeldige parameters onvoorspelbare resultaten veroorzaken.

Example

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

Roep deze methode aan om te testen of de matrix leeg is.

bool IsEmpty() const throw();

Retourwaarde

Retourneert waar als de matrix leeg is, anders onwaar.

Opmerkingen

De matrix wordt gezegd leeg te zijn als deze geen elementen bevat. Dus zelfs als de matrix lege elementen bevat, is deze niet leeg.

Example

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

Roep deze operator aan om een verwijzing naar een element in de matrix te retourneren.

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

Parameterwaarden

iElement
De indexwaarde van het matrixelement dat moet worden geretourneerd.

Retourwaarde

Retourneert een verwijzing naar het vereiste matrixelement.

Opmerkingen

Voert een vergelijkbare functie uit als CAtlArray::GetAt. In tegenstelling tot de MFC-klasse CArray kan deze operator niet worden gebruikt als vervanging voor CAtlArray::SetAt.

In builds voor foutopsporing wordt een ATLASSERT gegenereerd als iElement het totale aantal elementen in de matrix overschrijdt. In retail-builds kan een ongeldige parameter onvoorspelbare resultaten veroorzaken.

CAtlArray::OUTARGTYPE

Het gegevenstype dat moet worden gebruikt voor het ophalen van elementen uit de matrix.

typedef ETraits::OUTARGTYPE OUTARGTYPE;

CAtlArray::RemoveAll

Roep deze methode aan om alle elementen uit het matrixobject te verwijderen.

void RemoveAll() throw();

Opmerkingen

Hiermee verwijdert u alle elementen uit het matrixobject.

Met deze methode wordt CAtlArray::SetCount aangeroepen om het formaat van de matrix te wijzigen en wordt vervolgens toegewezen geheugen vrijgemaakt.

Example

Zie het voorbeeld voor CAtlArray::IsEmpty.

CAtlArray::RemoveAt

Roep deze methode aan om een of meer elementen uit de matrix te verwijderen.

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

Parameterwaarden

iElement
De index van het eerste element dat moet worden verwijderd.

nCount
Het aantal elementen dat moet worden verwijderd.

Opmerkingen

Hiermee verwijdert u een of meer elementen uit de matrix. Alle resterende elementen worden omlaag verplaatst. De bovengrens wordt afgebroken, maar het geheugen wordt pas vrijgemaakt als er een aanroep naar CAtlArray::FreeExtra wordt gemaakt.

In builds voor foutopsporing wordt een ATLASSERT gegenereerd als het CAtlArray object ongeldig is of als het gecombineerde totaal van iElement en nCount het totale aantal elementen in de matrix overschrijdt. In retail-builds kunnen ongeldige parameters onvoorspelbare resultaten veroorzaken.

Example

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

Roep deze methode aan om de waarde van een element in het matrixobject in te stellen.

void SetAt(size_t iElement, INARGTYPE element);

Parameterwaarden

iElement
De index die verwijst naar het matrixelement dat moet worden ingesteld.

element
De nieuwe waarde van het opgegeven element.

Opmerkingen

In builds voor foutopsporing wordt een ATLASSERT gegenereerd als iElement het aantal elementen in de matrix overschrijdt. In retail-builds kan een ongeldige parameter leiden tot onvoorspelbare resultaten.

Example

Zie het voorbeeld voor CAtlArray::GetAt.

CAtlArray::SetCount

Roep deze methode aan om de grootte van het matrixobject in te stellen.

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

Parameterwaarden

nNewSize
De vereiste grootte van de matrix.

nGrowBy
Een waarde die wordt gebruikt om te bepalen hoe groot de buffer is. Een waarde van -1 zorgt ervoor dat een intern berekende waarde wordt gebruikt.

Retourwaarde

Retourneert true als de grootte van de matrix is gewijzigd, anders onwaar.

Opmerkingen

De matrix kan worden vergroot of verkleind. Indien verhoogd, worden er extra lege elementen toegevoegd aan de matrix. Als dit is afgenomen, worden de elementen met de grootste indexen verwijderd en wordt geheugen vrijgemaakt.

Gebruik deze methode om de grootte van de matrix in te stellen voordat u deze gebruikt. Als SetCount dit niet wordt gebruikt, vermindert het proces van het toevoegen van elementen ( en de daaropvolgende geheugentoewijzing) de prestaties en het fragmentgeheugen.

Example

Zie het voorbeeld voor CAtlArray::GetData.

CAtlArray::SetAtGrow

Roep deze methode aan om de waarde van een element in het matrixobject in te stellen, waarbij de matrix naar behoefte wordt uitgebreid.

void SetAtGrow(size_t iElement, INARGTYPE element);

Parameterwaarden

iElement
De index die verwijst naar het matrixelement dat moet worden ingesteld.

element
De nieuwe waarde van het opgegeven element.

Opmerkingen

Vervangt de waarde van het element dat door de index wordt verwezen. Als iElement groter is dan de huidige grootte van de matrix, wordt de matrix automatisch verhoogd met behulp van een aanroep naar CAtlArray::SetCount. In builds voor foutopsporing wordt een ATLASSERT gegenereerd als het CAtlArray object ongeldig is. In retail-builds kunnen ongeldige parameters onvoorspelbare resultaten veroorzaken.

Example

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

Zie ook

MMXSwarm-voorbeeld
DynamicConsumer-voorbeeld
Voorbeeld updatePV
Voorbeeld van een selectiekader
CArray-klasse
Overzicht van klassen