Clase `CArray`

Artículo
06/16/2023

Admite matrices que se parecen a las matrices de C, pero puede reducirse y crecer dinámicamente según sea necesario.

Sintaxis

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

Parámetros

TYPE
Parámetro de plantilla que especifica el tipo de objetos almacenados en la matriz. TYPE es un parámetro devuelto por CArray.

ARG_TYPE
Parámetro de plantilla que especifica el tipo de argumento que se usa para tener acceso a los objetos almacenados en la matriz. A menudo una referencia a TYPE. ARG_TYPE es un parámetro que se pasa a CArray.

Miembros

Constructores públicos

Nombre	Descripción
`CArray::CArray`	Construye una matriz vacía.

Métodos públicos

Nombre	Descripción
`CArray::Add`	Agrega un elemento al final de la matriz; aumenta el tamaño de la matriz si es necesario.
`CArray::Append`	Anexa otra matriz a la matriz; aumenta el tamaño de la matriz si es necesario.
`CArray::Copy`	Copia otra matriz a la matriz; aumenta el tamaño de la matriz si es necesario.
`CArray::ElementAt`	Devuelve una referencia temporal al puntero del elemento dentro de la matriz.
`CArray::FreeExtra`	Libera toda la memoria no usada por encima del límite superior actual.
`CArray::GetAt`	Devuelve el valor en un índice dado.
`CArray::GetCount`	Obtiene el número de elementos de esta matriz.
`CArray::GetData`	Permite el acceso a los elementos de la matriz. Puede ser `NULL`.
`CArray::GetSize`	Obtiene el número de elementos de esta matriz.
`CArray::GetUpperBound`	Devuelve el índice válido de mayor tamaño.
`CArray::InsertAt`	Inserta un elemento (o todos los elementos de otra matriz) en un índice especificado.
`CArray::IsEmpty`	Determina si la matriz está vacía.
`CArray::RemoveAll`	Quita todos los elementos de esta matriz.
`CArray::RemoveAt`	Quita un elemento en un índice específico.
`CArray::SetAt`	Establece el valor de un índice dado; la matriz no puede aumentar de tamaño.
`CArray::SetAtGrow`	Establece el valor de un índice dado; aumenta el tamaño de la matriz si es necesario.
`CArray::SetSize`	Establece el número de elementos que contendrá esta matriz.

Operadores públicos

Nombre	Descripción
`operator[]`	Establece u obtiene el elemento en el índice especificado.

Comentarios

Los índices de matriz siempre comienzan en la posición 0. Puede decidir si corregir el límite superior o permitir que la matriz se expanda al agregar elementos más allá del límite actual. La memoria se asigna de manera contigua al límite superior, incluso si algunos elementos son NULL.

Nota:

La mayoría de los métodos que cambian el tamaño de un objeto CArray o que le agregan elementos usan memcpy_s para mover los elementos. Esto es un problema porque memcpy_s no es compatible con los objetos que requieren que se llame al constructor. Si los elementos de CArray no son compatibles con memcpy_s, debe crear un nuevo objeto CArray del tamaño adecuado. Luego, debe usar CArray::Copy y CArray::SetAt para rellenar la nueva matriz porque esos métodos usan un operador de asignación en lugar de memcpy_s.

Al igual que con una matriz de C, el tiempo de acceso de un elemento indexado CArray es constante y es independiente del tamaño de la matriz.

Sugerencia

Antes de usar una matriz, use SetSize para establecer su tamaño y asignarle memoria. Si no usa SetSize, al agregar elementos a la matriz, esta se reasigna y se copia con frecuencia. La reasignación y copia frecuentes son ineficaces y pueden fragmentar la memoria.

Si se necesita un volcado de elementos individuales en la matriz, debe establecer la profundidad del objeto CDumpContext en 1 o un valor superior.

Algunas funciones miembro de esta clase llaman a funciones auxiliares globales que se deben personalizar en la mayoría de los usos de la clase CArray. Consulte el tema Asistentes de clases de colección en la sección Macros y globales de MFC.

La derivación de clases de matriz es similar a la derivación de lista.

Para más información sobre el uso de CArray, consulte el artículo Colecciones.

Jerarquía de herencia

CObject

CArray

Requisitos

Encabezado: afxtempl.h

`CArray::Add`

Agrega un nuevo elemento al final de una matriz, aumentando la matriz en 1.

INT_PTR Add(ARG_TYPE newElement);

Parámetros

ARG_TYPE
Parámetro de plantilla que especifica el tipo de argumentos que hacen referencia a elementos de esta matriz.

newElement
Elemento que se va a agregar a esta matriz.

Valor devuelto

El índice del elemento agregado.

Comentarios

Si SetSize se ha usado con un valor nGrowBy mayor que 1, se puede asignar memoria adicional. Sin embargo, el límite superior aumentará solo en 1.

Ejemplo

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

Llame a esta función miembro para agregar el contenido de una matriz al final de otra.

INT_PTR Append(const CArray& src);

Parámetros

src
Origen de los elementos que se van a anexar a una matriz.

Valor devuelto

Índice del primer elemento anexado.

Comentarios

Las matrices deben ser del mismo tipo.

Si es necesario, Append puede asignar memoria adicional para acomodar los elementos anexados a la matriz.

Ejemplo

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`

Construye una matriz vacía.

CArray();

Comentarios

La matriz crece un elemento cada vez.

Ejemplo

CArray<CPoint, CPoint> ptArray;

`CArray::Copy`

Use esta función miembro para copiar los elementos de una matriz en otra.

void Copy(const CArray& src);

Parámetros

src
Origen de los elementos que se vayan a copiar en una matriz.

Comentarios

Llame a esta función miembro para sobrescribir los elementos de una matriz con los elementos de otra.

Copy no libera memoria; sin embargo, si es necesario, Copy puede asignar memoria adicional para dar cabida a los elementos copiados en la matriz.

Ejemplo

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`

Devuelve una referencia temporal al elemento especificado dentro de la matriz.

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

Parámetros

nIndex
Índice entero mayor o igual que 0 y menor o igual que el valor devuelto por GetUpperBound.

Valor devuelto

Referencia a un elemento de matriz.

Comentarios

Se usa para implementar el operador de asignación del lado izquierdo de las matrices.

Ejemplo

Vea el ejemplo de GetSize.

`CArray::FreeExtra`

Libera memoria adicional que se haya asignado mientras crecía la matriz.

void FreeExtra();

Comentarios

Esta función no tiene ningún efecto sobre el tamaño o el límite superior de la matriz.

Ejemplo

Vea el ejemplo de GetData.

`CArray::GetAt`

Devuelve el elemento de matriz que se encuentra en el índice especificado.

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

Parámetros

TYPE
Parámetro de plantilla que especifica el tipo de los elementos de matriz.

nIndex
Índice entero mayor o igual que 0 y menor o igual que el valor devuelto por GetUpperBound.

Valor devuelto

Elemento de matriz que se encuentra actualmente en este índice.

Comentarios

Si se pasa un valor negativo o un valor mayor que el valor devuelto por GetUpperBound, se producirá un error en la aserción.

Ejemplo

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`

Devuelve el número de elementos de matriz.

INT_PTR GetCount() const;

Valor devuelto

Número de elementos de la matriz.

Comentarios

Llame a este método para recuperar el número de elementos de la matriz. Dado que los índices se basan en cero, el tamaño es 1 mayor que el índice más grande. Al llamar a este método, se generará el mismo resultado que con el método CArray::GetSize.

Ejemplo

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`

Use esta función miembro para obtener acceso directo a los elementos de una matriz.

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

Parámetros

TYPE
Parámetro de plantilla que especifica el tipo de los elementos de matriz.

Valor devuelto

Puntero a un elemento de matriz.

Comentarios

Si no hay elementos disponibles, GetData devuelve un valor NULL.

Aunque el acceso directo a los elementos de una matriz puede ayudarle a trabajar más rápidamente, tenga cuidado al llamar a GetData; los errores que cometa afectan directamente a los elementos de la matriz.

Ejemplo

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`

Devuelve el tamaño de la matriz.

INT_PTR GetSize() const;

Comentarios

Dado que los índices se basan en cero, el tamaño es 1 mayor que el índice más grande. Al llamar a este método, se generará el mismo resultado que con el método CArray::GetCount.

Ejemplo

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`

Devuelve el límite superior actual de esta matriz.

INT_PTR GetUpperBound() const;

Comentarios

Dado que los índices de matriz se basan en cero, esta función devuelve un valor 1 menor que GetSize.

La condición GetUpperBound( ) = -1 indica que la matriz no contiene ningún elemento.

Ejemplo

Vea el ejemplo de CArray::GetAt.

`CArray::InsertAt`

La primera versión de InsertAt inserta un elemento (o varias copias de un elemento) en un índice especificado de una matriz.

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

void InsertAt(
    INT_PTR nStartIndex,
    CArray* pNewArray);

Parámetros

nIndex
Índice entero que puede ser mayor que el valor devuelto por GetUpperBound.

ARG_TYPE
Parámetro de plantilla que especifica el tipo de elementos de esta matriz.

newElement
Elemento que se va a colocar en esta matriz.

nCount
Número de veces que se debe insertar este elemento (el valor predeterminado es 1).

nStartIndex
Índice entero que puede ser mayor que el valor devuelto por GetUpperBound.

pNewArray
Otra matriz que contiene elementos que se van a agregar a esta matriz.

Comentarios

En el proceso, desplaza hacia arriba (incrementando el índice) el elemento existente en este índice y desplaza hacia arriba todos los elementos por encima de él.

La segunda versión inserta todos los elementos de otra colección CArray, empezando por la posición nStartIndex.

La función SetAt, en cambio, reemplaza un elemento de matriz especificado y no desplaza ningún elemento.

Ejemplo

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

Determina si la matriz está vacía.

BOOL IsEmpty() const;

Valor devuelto

Distinto de cero si la matriz no contiene elementos; de lo contrario, 0.

`CArray::operator []`

Estos operadores de subíndice son un buen sustituto de las funciones SetAt y GetAt.

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

Parámetros

TYPE
Parámetro de plantilla que especifica el tipo de elementos de esta matriz.

nIndex
Índice del elemento al que se tendrá acceso.

Comentarios

El primer operador, llamado para las matrices que no son const, se puede usar a la derecha (r-value) o a la izquierda (l-value) de una instrucción de asignación. El segundo, llamado para las matrices const, solo se puede usar a la derecha.

La versión de depuración de la biblioteca afirma si el subíndice (ya sea en el lado izquierdo o derecho de una instrucción de asignación) está fuera de los límites.

Ejemplo

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`

Reubica los datos en un nuevo búfer cuando la matriz debe crecer o reducirse.

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

Parámetros

pNewData
Nuevo búfer para la matriz de elementos.

pData
Matriz antigua de elementos.

nCount
Cantidad de elementos de la matriz antigua.

Comentarios

pNewData es siempre lo bastante grande como para contener todos los elementos pData.

La implementación CArray usa este método para copiar los datos antiguos en un nuevo búfer cuando la matriz debe crecer o reducirse (cuando se llama a SetSize o FreeExtra). La implementación predeterminada simplemente copia los datos.

Para las matrices en las que un elemento contiene un puntero a uno de sus propios miembros, u otra estructura contiene un puntero a uno de los elementos de la matriz, los punteros no se actualizan en la copia sin formato. En este caso, puede corregir punteros mediante la implementación de una especialización de RelocateElements con los tipos pertinentes. Usted también es responsable de la copia de datos.

`CArray::RemoveAll`

Quita todos los elementos de esta matriz.

void RemoveAll();

Comentarios

Si la matriz ya está vacía, la función sigue funcionando.

Ejemplo

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`

Quita uno o varios elementos que comienzan en un índice especificado de una matriz.

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

Parámetros

nIndex
Índice entero mayor o igual que 0 y menor o igual que el valor devuelto por GetUpperBound.

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

Comentarios

En el proceso, desplaza hacia abajo todos los elementos situados encima de los elementos quitados. Disminuye el límite superior de la matriz, pero no libera memoria.

Si intenta quitar más elementos de los contenidos en la matriz por encima del punto de eliminación, se produce una aserción en la versión de depuración de la biblioteca.

Ejemplo

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`

Establece el elemento de matriz en el índice especificado.

void SetAt(INT_PTR nIndex, ARG_TYPE newElement);

Parámetros

nIndex
Índice entero mayor o igual que 0 y menor o igual que el valor devuelto por GetUpperBound.

ARG_TYPE
Parámetro de plantilla que especifica el tipo de argumentos que se usan para hacer referencia a los elementos de una matriz.

newElement
Nuevo valor de elemento que se va a almacenar en la posición especificada.

Comentarios

SetAt no hará que la matriz crezca. Use SetAtGrow si quiere que la matriz crezca automáticamente.

Debe asegurarse de que el valor de índice represente una posición válida en la matriz. Si está fuera de los límites, se realiza una aserción en la versión de depuración de la biblioteca.

Ejemplo

Vea el ejemplo de GetAt.

`CArray::SetAtGrow`

Establece el elemento de matriz en el índice especificado.

void SetAtGrow(INT_PTR nIndex, ARG_TYPE newElement);

Parámetros

nIndex
Índice entero mayor o igual que 0.

ARG_TYPE
Parámetro de plantilla que especifica el tipo elementos de la matriz.

newElement
Elemento que se va a agregar a esta matriz. Se permite un valor NULL.

Comentarios

La matriz crece automáticamente si es necesario (es decir, el límite superior se ajusta para acomodar el nuevo elemento).

Ejemplo

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

Establece el tamaño de una matriz vacía o existente; asigna memoria si es necesario.

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

Parámetros

nNewSize
Nuevo tamaño de matriz (número de elementos). Debe ser mayor o igual que 0.

nGrowBy
Número mínimo de ranuras de elemento que se van a asignar si es necesario un aumento de tamaño.

Comentarios

Si el nuevo tamaño es menor que el tamaño anterior, la matriz se trunca y se libera toda la memoria no utilizada.

Use esta función para establecer el tamaño de la matriz antes de empezar a usar la matriz. Si no usa SetSize, al agregar elementos a la matriz, esta se reasigna y se copia con frecuencia. La reasignación y copia frecuentes son ineficaces y pueden fragmentar la memoria.

El parámetro nGrowBy afecta a la asignación de memoria interna mientras la matriz crece. Su uso nunca afecta al tamaño de la matriz según lo notificado por GetSize y GetUpperBound. Si se usa el valor predeterminado, MFC asigna memoria de una manera calculada para evitar la fragmentación de memoria y optimizar la eficiencia en la mayoría de los casos.

Ejemplo

Vea el ejemplo de GetData.

Consulte también

Ejemplo de MFCCOLLECT
CObject (clase)
Gráfico de jerarquías
CObArray (clase)
Asistentes de clase de colección

Compartir a través de

Clase CArray

Sintaxis

Parámetros

Miembros

Constructores públicos

Métodos públicos

Operadores públicos

Comentarios

Jerarquía de herencia

Requisitos

CArray::Add

Parámetros

Valor devuelto

Comentarios

Ejemplo

CArray::Append

Parámetros

Valor devuelto

Comentarios

Ejemplo

CArray::CArray

Comentarios

Ejemplo

CArray::Copy

Parámetros

Comentarios

Ejemplo

CArray::ElementAt

Parámetros

Valor devuelto

Comentarios

Ejemplo

CArray::FreeExtra

Comentarios

Ejemplo

CArray::GetAt

Parámetros

Valor devuelto

Comentarios

Ejemplo

CArray::GetCount

Valor devuelto

Comentarios

Ejemplo

CArray::GetData

Parámetros

Valor devuelto

Comentarios

Ejemplo

CArray::GetSize

Comentarios

Ejemplo

CArray::GetUpperBound

Comentarios

Ejemplo

CArray::InsertAt

Parámetros

Comentarios

Ejemplo

CArray::IsEmpty

Valor devuelto

CArray::operator []

Parámetros

Comentarios

Ejemplo

CArray::RelocateElements

Parámetros

Comentarios

CArray::RemoveAll

Comentarios

Ejemplo

CArray::RemoveAt

Parámetros

Comentarios

Ejemplo

CArray::SetAt

Parámetros

Comentarios

Ejemplo

Clase `CArray`

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