CAtlArray (clase)

Esta clase implementa un objeto de matriz.

Sintaxis

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

Parámetros

E
Tipo de datos que se va a almacenar en la matriz.

ETraits
Código usado para copiar o mover elementos.

Miembros

Métodos

Función	Descripción
Add (Agregar)	Llame a este método para agregar un elemento al objeto de matriz.
Anexar	Llame a este método para agregar el contenido de una matriz al final de otra.
AssertValid	Llame a este método para confirmar que el objeto de matriz es válido.
CAtlArray	Constructor .
~CAtlArray	El destructor .
Copiar	Llame a este método para copiar los elementos de una matriz en otra.
FreeExtra	Llame a este método para quitar los elementos vacíos de la matriz.
GetAt	Llame a este método para recuperar un único elemento del objeto de matriz.
GetCount	Llame a este método para devolver el número de elementos almacenados en la matriz.
GetData	Llame a este método para devolver un puntero al primer elemento de la matriz.
InsertArrayAt	Llame a este método para insertar una matriz en otra.
InsertAt	Llame a este método para insertar un nuevo elemento (o varias copias de un elemento) en el objeto de matriz.
IsEmpty	Llame a este método para probar si la matriz está vacía.
RemoveAll	Llame a este método para quitar todos los elementos del objeto de matriz.
RemoveAt	Llame a este método para quitar uno o varios elementos de la matriz.
SetAt	Llame a este método para establecer el valor de un elemento en el objeto de matriz.
SetAtGrow	Llame a este método para establecer el valor de un elemento en el objeto de matriz, expandiendo la matriz según sea necesario.
SetCount	Llame a este método para establecer el tamaño del objeto de matriz.

Operadores

Operador	Descripción
operator []	Llame a este operador para devolver una referencia a un elemento de la matriz.

Typedefs

Definición de tipo	Descripción
INARGTYPE	Tipo de datos que se va a usar para agregar elementos a la matriz.
OUTARGTYPE	Tipo de datos que se va a usar para recuperar elementos de la matriz.

Comentarios

CAtlArray proporciona métodos para crear y administrar una matriz de elementos de un tipo definido por el usuario. Aunque es similar a las matrices de C estándar, el objeto CAtlArray puede reducir y crecer dinámicamente según sea necesario. El índice de matriz siempre comienza en la posición 0 y el límite superior se puede corregir o se puede expandir a medida que se agregan nuevos elementos.

Para matrices con un pequeño número de elementos, se puede usar la clase ATL CSimpleArray.

CAtlArray está estrechamente relacionado con la clase CArray de MFC y funcionará en un proyecto de MFC, aunque sin compatibilidad con la serialización.

Para obtener más información, consulte Clases de colección en ATL.

Requisitos

Encabezado: atlcoll.h

CAtlArray::Add

Llame a este método para agregar un elemento al objeto de matriz.

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

Parámetros

element
Elemento que se va a agregar a la matriz.

Valor devuelto

Índice del elemento agregado.

Comentarios

El nuevo elemento se agrega al final de la matriz. Si no se proporciona ningún elemento, se agrega un elemento vacío; es decir, la matriz aumenta de tamaño como si se hubiera agregado un elemento real. Si se produce un error en la operación, se llama a AtlThrow con el argumento E_OUTOFMEMORY.

Ejemplo

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

Llame a este método para agregar el contenido de una matriz al final de otra.

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

Parámetros

aSrc
Matriz que se va a anexar.

Valor devuelto

Devuelve el índice del primer elemento anexado.

Comentarios

Los elementos de la matriz proporcionada se agregan al final de la matriz existente. Si es necesario, se asignará memoria para acomodar los nuevos elementos.

Las matrices deben ser del mismo tipo y no es posible anexar una matriz a sí misma.

En las compilaciones de depuración, se generará un ATLASSERT si el argumento CAtlArray no es una matriz válida o si aSrc hace referencia al mismo objeto. En las compilaciones de versión, los argumentos no válidos pueden provocar un comportamiento impredecible.

Ejemplo

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

Llame a este método para confirmar que el objeto de matriz es válido.

void AssertValid() const;

Comentarios

Si el objeto de matriz no es válido, ATLASSERT iniciará una aserción. Este método solo está disponible si se define _DEBUG.

Ejemplo

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

CAtlArray::CAtlArray

Constructor .

CAtlArray() throw();

Comentarios

Inicializa el objeto de matriz.

Ejemplo

CAtlArray<int> iArray;   

CAtlArray::~CAtlArray

El destructor .

~CAtlArray() throw();

Comentarios

Libera los recursos utilizados por el objeto de matriz.

CAtlArray::Copy

Llame a este método para copiar los elementos de una matriz en otra.

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

Parámetros

aSrc
Origen de los elementos que se van a copiar en una matriz.

Comentarios

Llame a este método para sobrescribir elementos de una matriz con los elementos de otra matriz. Si es necesario, se asignará memoria para acomodar los nuevos elementos. No es posible copiar elementos de una matriz en sí misma.

Si se va a conservar el contenido existente de la matriz, use CAtlArray::Append en su lugar.

En las compilaciones de depuración, se generará un ATLASSERT si el objeto existente CAtlArray no es válido o si aSrc hace referencia al mismo objeto. En las compilaciones de versión, los argumentos no válidos pueden provocar un comportamiento impredecible.

Nota:

CAtlArray::Copy no admite matrices que constan de elementos creados con la clase CAutoPtr .

Ejemplo

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

Llame a este método para quitar los elementos vacíos de la matriz.

void FreeExtra() throw();

Comentarios

Se quitan los elementos vacíos, pero el tamaño y el límite superior de la matriz permanecen sin cambios.

En las compilaciones de depuración, se generará un ATLASSERT si el objeto CAtlArray no es válido o si la matriz superaría su tamaño máximo.

CAtlArray::GetAt

Llame a este método para recuperar un único elemento del objeto de matriz.

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

Parámetros

iElement
Valor de índice del elemento de matriz que se va a devolver.

Valor devuelto

Devuelve una referencia al prototipo para una matriz.

Comentarios

En las compilaciones de depuración, se generará un ATLASSERT si iElement supera el número de elementos de la matriz. En las compilaciones de versión, un argumento no válido puede provocar un comportamiento impredecible.

Ejemplo

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

Llame a este método para devolver el número de elementos almacenados en la matriz.

size_t GetCount() const throw();

Valor devuelto

Devuelve el número de elementos almacenados en la matriz.

Comentarios

Como el primer elemento de la matriz está en la posición 0, el valor devuelto por GetCount siempre es 1 mayor que el índice más grande.

Ejemplo

Consulte el ejemplo de CAtlArray::GetAt.

CAtlArray::GetData

Llame a este método para devolver un puntero al primer elemento de la matriz.

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

Valor devuelto

Devuelve un puntero al primer elemento de la matriz. Si no hay elementos disponibles, se devuelve NULL.

Ejemplo

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

Tipo de datos que se va a usar para agregar elementos a la matriz.

typedef ETraits::INARGTYPE INARGTYPE;

CAtlArray::InsertArrayAt

Llame a este método para insertar una matriz en otra.

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

Parámetros

iStart
Índice en el que se va a insertar la matriz.

paNew
Matriz que se va a insertar.

Comentarios

Los elementos de la matriz paNew se copian en el objeto de matriz, empezando por el elemento iStart. Los elementos de matriz existentes se mueven para evitar que se sobrescriban.

En las compilaciones de depuración, se generará un ATLASSERT si el objeto CAtlArray no es válido o si el puntero paNew es null o no es válido.

Nota:

CAtlArray::InsertArrayAt no admite matrices que constan de elementos creados con la clase CAutoPtr .

Ejemplo

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

Llame a este método para insertar un nuevo elemento (o varias copias de un elemento) en el objeto de matriz.

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

Parámetros

iElement
Índice donde se van a insertar el elemento o los elementos.

element
Valor de carácter de los elementos que se van a insertar.

nCount
Número de elementos que se van a omitir.

Comentarios

Inserta uno o varios elementos en la matriz, empezando por el índice iElement. Los elementos existentes se mueven para evitar que se sobrescriban.

En las compilaciones de depuración, se generará un ATLASSERT si el objeto CAtlArray no es válido, el número de elementos que se van a agregar es cero o el número combinado de elementos es demasiado grande para que la matriz contenga. En las compilaciones comerciales, el paso de parámetros no válidos puede provocar resultados imprevisibles.

Ejemplo

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

Llame a este método para probar si la matriz está vacía.

bool IsEmpty() const throw();

Valor devuelto

Devuelve TRUE si el mapa está vacío; si no, FALSE.

Comentarios

Se dice que la matriz está vacía si no contiene ningún elemento. Por lo tanto, incluso si la matriz contiene elementos vacíos, no está vacío.

Ejemplo

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

Llame a este operador para devolver una referencia a un elemento de la matriz.

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

Parámetros

iElement
Valor de índice del elemento de matriz que se va a devolver.

Valor devuelto

Devuelve una referencia al prototipo para una matriz.

Comentarios

Realiza una función similar a CAtlArray::GetAt. A diferencia de la clase MFC CArray, este operador no se puede usar como sustituto de CAtlArray::SetAt.

En las compilaciones de depuración, se generará un ATLASSERT si iElement supera el número total de elementos de la matriz. En las compilaciones comerciales, un parámetro no válido puede provocar resultados imprevisibles.

CAtlArray::OUTARGTYPE

Tipo de datos que se va a usar para recuperar elementos de la matriz.

typedef ETraits::OUTARGTYPE OUTARGTYPE;

CAtlArray::RemoveAll

Llame a este método para quitar todos los elementos del objeto de matriz.

void RemoveAll() throw();

Comentarios

Quita todos los elementos del objeto de matriz.

Este método llama a CAtlArray::SetCount para cambiar el tamaño de la matriz y, posteriormente, libera cualquier memoria asignada.

Ejemplo

Consulte el ejemplo de CAtlArray::IsEmpty.

CAtlArray::RemoveAt

Llame a este método para quitar uno o varios elementos de la matriz.

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

Parámetros

iElement
Índice del primer elemento que se va a ordenar.

nCount
Número de elementos que se va a quitar.

Comentarios

Quita uno o varios elementos de la matriz. Los elementos restantes se desplazan hacia abajo. El límite superior se disminuye, pero la memoria no se libera hasta que se realiza una llamada a CAtlArray::FreeExtra.

En las compilaciones de depuración, se generará un ATLASSERT si el objeto CAtlArray no es válido o si el total combinado de iElement y nCount supera el número total de elementos de la matriz. En las compilaciones comerciales, los parámetros no válidos pueden provocar resultados impredecibles.

Ejemplo

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

Llame a este método para establecer el valor de un elemento en el objeto de matriz.

void SetAt(size_t iElement, INARGTYPE element);

Parámetros

iElement
Índice que apunta al elemento de matriz que se va a establecer.

element
Nuevo valor del elemento especificado.

Comentarios

En las compilaciones de depuración, se generará un ATLASSERT si iElement supera el número de elementos de la matriz. En las compilaciones comerciales, un parámetro no válido puede dar lugar a resultados imprevisibles.

Ejemplo

Consulte el ejemplo de CAtlArray::GetAt.

CAtlArray::SetCount

Llame a este método para establecer el tamaño del objeto de matriz.

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

Parámetros

nNewSize
Tamaño requerido de la matriz.

nGrowBy
Valor que se usa para determinar el tamaño del búfer. Un valor de -1 hace que se use un valor calculado internamente.

Valor devuelto

Devuelve true si la matriz se cambia correctamente de tamaño; en caso contrario, false.

Comentarios

La matriz se puede aumentar o reducir en tamaño. Si aumenta, se agregan elementos vacíos adicionales a la matriz. Si se reduce, los elementos con los índices más grandes se eliminarán y se liberará memoria.

Use este método para establecer el tamaño de la matriz antes de usarlo. Si no se usa SetCount, el proceso de agregar elementos (y la asignación de memoria posterior realizada) reducirá el rendimiento y la memoria de fragmentos.

Ejemplo

Consulte el ejemplo de CAtlArray::GetData.

CAtlArray::SetAtGrow

Llame a este método para establecer el valor de un elemento en el objeto de matriz, expandiendo la matriz según sea necesario.

void SetAtGrow(size_t iElement, INARGTYPE element);

Parámetros

iElement
Índice que apunta al elemento de matriz que se va a establecer.

element
Nuevo valor del elemento especificado.

Comentarios

Reemplaza el valor del elemento al que apunta el índice. Si iElement es mayor que el tamaño actual de la matriz, la matriz aumenta automáticamente con una llamada a CAtlArray::SetCount. En las compilaciones de depuración, se generará un ATLASSERT si el objeto CAtlArray no es válido. En las compilaciones comerciales, los parámetros no válidos pueden provocar resultados impredecibles.

Ejemplo

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

Vea también

MMXSwarm Sample
Ejemplo DynamicConsumer
UpdatePV Sample
Ejemplo de marquesina
CArray (clase)
Información general sobre la clase