Compartir a través de


Clase CList

Admite listas ordenadas de objetos no únicos accesibles secuencialmente o por valor.

Sintaxis

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

Miembros

Constructores públicos

Nombre Descripción
CList::CList Construye una lista ordenada vacía.

Métodos públicos

Nombre Descripción
CList::AddHead Agrega un elemento (o todos los elementos de otra lista) al principio de la lista (crea un principio nuevo).
CList::AddTail Agrega un elemento (o todos los elementos de otra lista) al final de la lista (crea un final nuevo).
CList::Find Obtiene la posición de un elemento especificado por el valor de puntero.
CList::FindIndex Obtiene la posición de un elemento especificado por un índice basado en cero.
CList::GetAt Obtiene el elemento en una posición determinada.
CList::GetCount Devuelve el número de elementos en esta lista.
CList::GetHead Devuelve el elemento del encabezado de la lista (no puede estar vacío).
CList::GetHeadPosition Devuelve la posición del elemento de encabezado de la lista.
CList::GetNext Obtiene el siguiente elemento para iterar.
CList::GetPrev Obtiene el elemento anterior para su iteración.
CList::GetSize Devuelve el número de elementos en esta lista.
CList::GetTail Devuelve el elemento del final de la lista (no puede estar vacío).
CList::GetTailPosition Devuelve la posición del elemento del final de la lista.
CList::InsertAfter Inserta un elemento nuevo después de una posición determinada.
CList::InsertBefore Inserta un elemento nuevo antes de una posición determinada.
CList::IsEmpty Comprueba la condición de lista vacía (sin elementos).
CList::RemoveAll Quita todos los elementos de esta lista.
CList::RemoveAt Quita un elemento de esta lista, especificado por posición.
CList::RemoveHead Quita el elemento del principio de la lista.
CList::RemoveTail Quita el elemento del final de la lista.
CList::SetAt Establece el elemento en una posición determinada.

Parámetros

TYPE
Tipo de objeto almacenado en la lista.

ARG_TYPE
Tipo utilizado para hacer referencia a objetos almacenados en la lista. Puede ser una referencia.

Comentarios

Las listas CList se comportan como listas doblemente vinculadas.

Una variable de tipo POSITION es una clave para la lista. Puede usar una variable POSITION como iterador para recorrer una lista secuencialmente y como marcador para contener un lugar. Sin embargo, una posición no es lo mismo que un índice.

La inserción de elementos es muy rápida en el encabezado de la lista, en el final y en una POSITION conocida. Una búsqueda secuencial es necesaria para buscar un elemento por valor o índice. Esta búsqueda puede ser lenta si la lista es larga.

Si se necesita un volcado de elementos individuales en la lista, se debe establecer la profundidad del contexto de volcado 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 CList. Consulte Asistentes de clase de colección en la sección "Macros y variables globales".

Para más información sobre cómo usar CList, consulte el artículo Colecciones.

Ejemplo

// CList is a template class that takes two template arguments.
// The first argument is type stored internally by the list, the
// second argument is the type used in the arguments for the
// CList methods.

// This code defines a list of ints.
CList<int, int> myIntList;

// This code defines a list of CStrings
CList<CString, CString &> myStringList;

// This code defines a list of MYTYPEs,
// NOTE: MYTYPE could be any struct, class or type definition
CList<MYTYPE, MYTYPE &> myTypeList;

Jerarquía de herencia

CObject

CList

Requisitos

Encabezadoafxtempl.h:

CList::AddHead

Agrega un nuevo elemento o lista de elementos al encabezado de esta lista.

POSITION AddHead(ARG_TYPE newElement);
void AddHead(CList* pNewList);

Parámetros

ARG_TYPE
Parámetro de plantilla que especifica el tipo de elemento de lista (puede ser una referencia).

newElement
Nuevo elemento.

pNewList
Puntero a otra lista CList. Los elementos de pNewList se agregarán a esta lista.

Valor devuelto

La primera versión devuelve el valor POSITION del elemento recién insertado.

Comentarios

La lista puede estar vacía antes de la operación.

Ejemplo

// Declarations of the variables used in the example
CList<CString, CString &> myList;
CList<CString, CString &> myList2;

// There are two versions of CList::AddHead: one adds a single
// element to the front of the list, the second adds another list
// to the front.

// This adds the string "ABC" to the front of myList.
// myList is a list of CStrings (ie defined as CList<CString,CString&>).
myList.AddHead(CString(_T("ABC")));

// This adds the elements of myList2 to the front of myList.
myList.AddHead(&myList2);

CList::AddTail

Agrega un nuevo elemento o lista de elementos al final de esta lista.

POSITION AddTail(ARG_TYPE newElement);
void AddTail(CList* pNewList);

Parámetros

ARG_TYPE
Parámetro de plantilla que especifica el tipo de elemento de lista (puede ser una referencia).

newElement
Elemento que se va a agregar a esta lista.

pNewList
Puntero a otra lista CList. Los elementos de pNewList se agregarán a esta lista.

Valor devuelto

La primera versión devuelve el valor POSITION del elemento recién insertado.

Comentarios

La lista puede estar vacía antes de la operación.

Ejemplo

// Define myList and myList2.
CList<CString, CString &> myList;
CList<CString, CString &> myList2;

// Add elements to the end of myList and myList2.
myList.AddTail(CString(_T("A")));
myList.AddTail(CString(_T("B")));
myList2.AddTail(CString(_T("C")));
myList2.AddTail(CString(_T("D")));

// There are two versions of CList::AddTail: one adds a single
// element to the end of the list, the second adds another list
// to the end.

// This adds the string "ABC" to the end of myList.
// myList is a list of CStrings (ie defined as CList<CString,CString&>).
myList.AddTail(CString(_T("ABC")));
ASSERT(CString(_T("ABC")) == myList.GetTail());

// This adds the elements of myList2 to the end of myList.
myList.AddTail(&myList2);

CList::CList

Construye una lista ordenada vacía.

CList(INT_PTR nBlockSize = 10);

Parámetros

nBlockSize
Granularidad de asignación de memoria para extender la lista.

Comentarios

A medida que crece la lista, la memoria se asigna en unidades de entradas nBlockSize.

Ejemplo

// This code defines myList as a list of strings
// such that memory gets allocated in chunks of
// 16 strings.
CList<CString, CString &> myList(16);

// This code defines myList2 as a list of ints
// such that memory gets allocated in chunks of
// 128 ints.
CList<int, int> myList2(128);

CList::Find

Recorre secuencialmente en la lista para buscar el primer elemento que coincida con el searchValue especificado.

POSITION Find(
    ARG_TYPE searchValue,
    POSITION startAfter = NULL) const;

Parámetros

ARG_TYPE
Parámetro de plantilla que especifica el tipo de elemento de lista (puede ser una referencia).

searchValue
Valor que se va a buscar en la lista.

startAfter
Posición inicial de la búsqueda. Si no se especifica ningún valor, la búsqueda comienza con el elemento del encabezado.

Valor devuelto

Valor POSITION que se puede usar para la recuperación de puntero de objeto o iteración; NULL si no se encuentra el objeto.

Ejemplo

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddHead(CString(_T("XYZ")));
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Find a specific element.
POSITION pos = myList.Find(CString(_T("XYZ")));
ASSERT(CString(_T("XYZ")) == myList.GetAt(pos));

CList::FindIndex

Usa el valor de nIndex como índice en la lista.

POSITION FindIndex(INT_PTR nIndex) const;

Parámetros

nIndex
Índice de base cero del elemento de lista que se va a buscar.

Valor devuelto

Valor POSITION que se puede usar para la recuperación de puntero de objeto o iteración; NULL si nIndex es negativo o demasiado grande.

Comentarios

Inicia un examen secuencial desde el encabezado de la lista y se detiene en el elemento n.

Ejemplo

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Verify the first element (index 0).
ASSERT(CString(_T("XYZ")) == myList.GetAt(myList.FindIndex(0)));

// Verify the third element (index 2).
ASSERT(CString(_T("123")) == myList.GetAt(myList.FindIndex(2)));

CList::GetAt

Obtiene el elemento de lista en una posición determinada.

TYPE& GetAt(POSITION position);
const TYPE& GetAt(POSITION position) const;

Parámetros

TYPE
Parámetro de plantilla que especifica el tipo de objeto en la lista.

position
Posición en la lista del elemento que se va a obtener.

Valor devuelto

Consulte la descripción del valor devuelto para GetHead.

Comentarios

GetAt devuelve el elemento (o una referencia al elemento ) asociado a una posición determinada. No es lo mismo que un índice y no puede trabajar usted mismo con un valor POSITION. Una variable de tipo POSITION es una clave para la lista.

Debe asegurarse de que el valor POSITION representa una posición válida en la lista. Si no es válida, se impone la versión de depuración de la biblioteca MFC (Microsoft Foundation Class).

Ejemplo

Vea el ejemplo de CList::GetHeadPosition.

CList::GetCount

Obtiene el número de elementos de esta lista.

INT_PTR GetCount() const;

Valor devuelto

Valor entero que contiene el recuento de elementos.

Comentarios

Al llamar a este método, se generará el mismo resultado que con el método CList::GetSize.

Ejemplo

Vea el ejemplo de CList::RemoveHead.

CList::GetHead

Obtiene el elemento del encabezado (o una referencia al elemento del encabezado) de esta lista.

const TYPE& GetHead() const;

TYPE& GetHead();

Parámetros

TYPE
Parámetro de plantilla que especifica el tipo de objeto en la lista.

Valor devuelto

Si la lista es const, GetHead devuelve una copia del elemento que se encuentra en el encabezado de la lista. Esto permite usar la función solo en el lado derecho de una instrucción de asignación y protege la lista frente a modificaciones.

Si la lista no es const, GetHead devuelve una referencia al elemento que se encuentra en el encabezado de la lista. Esto permite usar la función en cualquier lado de una instrucción de asignación y, por tanto, permite modificar las entradas de la lista.

Comentarios

Debe asegurarse de que la lista no esté vacía antes de llamar a GetHead. Si lo está, se impone la versión de depuración de la biblioteca MFC (Microsoft Foundation Class). Use IsEmpty para comprobar que la lista contiene elementos.

Ejemplo

// Define myList.
CList<CString, CString &> myList;

// Add an element to the front of the list.
myList.AddHead(CString(_T("ABC")));

// Verify the element was added to the front of the list.
ASSERT(CString(_T("ABC")) == myList.GetHead());

CList::GetHeadPosition

Obtiene la posición del elemento del encabezado de esta lista.

POSITION GetHeadPosition() const;

Valor devuelto

Valor POSITION que se puede usar para la recuperación de puntero de objeto o iteración; NULL si la lista está vacía.

Ejemplo

// Define myList.
CList<CString, CString &> myList;

// Add an element to the front of the list.
myList.AddHead(CString(_T("ABC")));

// Verify the element at the head position
// is the one added.
POSITION pos = myList.GetHeadPosition();
ASSERT(CString(_T("ABC")) == myList.GetAt(pos));

CList::GetNext

Obtiene el elemento de la lista identificado por rPosition y, luego, establece rPosition en el valor POSITION de la entrada siguiente de la lista.

TYPE& GetNext(POSITION& rPosition);
const TYPE& GetNext(POSITION& rPosition) const;

Parámetros

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

rPosition
Referencia a un valor POSITION devuelto por una llamada anterior de GetNext, GetHeadPosition u otra función miembro.

Valor devuelto

Si la lista es const, GetNext devuelve una copia de un elemento de la lista. Esto permite usar la función solo en el lado derecho de una instrucción de asignación y protege la lista frente a modificaciones.

Si la lista no es const, GetNext devuelve una referencia a un elemento de la lista. Esto permite usar la función en cualquier lado de una instrucción de asignación y, por tanto, permite modificar las entradas de la lista.

Comentarios

Puede usar GetNext en un bucle de iteración hacia delante si establece la posición inicial con una llamada a GetHeadPosition o Find.

Debe asegurarse de que el valor POSITION representa una posición válida en la lista. Si no es válida, se impone la versión de depuración de la biblioteca MFC (Microsoft Foundation Class).

Si el elemento recuperado es el último de la lista, el valor nuevo de rPosition se establece en NULL.

Ejemplo

// Define myList.
// Define myList.
CList<CString, CString &> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Dump the list elements to the debug window.
POSITION pos = myList.GetHeadPosition();
for (int i = 0; i < myList.GetCount(); i++)
{
   TRACE(_T("%s\r\n"), (LPCTSTR)myList.GetNext(pos));
}

CList::GetPrev

Obtiene el elemento de la lista identificado por rPosition y, luego, establece rPosition en el valor POSITION de la entrada anterior de la lista.

TYPE& GetPrev(POSITION& rPosition);
const TYPE& GetPrev(POSITION& rPosition) const;

Parámetros

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

rPosition
Referencia a un valor POSITION devuelto por una llamada anterior de GetPrev u otra función miembro.

Valor devuelto

Si la lista es const, GetPrev devuelve una copia del elemento que se encuentra en el encabezado de la lista. Esto permite usar la función solo en el lado derecho de una instrucción de asignación y protege la lista frente a modificaciones.

Si la lista no es const, GetPrev devuelve una referencia a un elemento de la lista. Esto permite usar la función en cualquier lado de una instrucción de asignación y, por tanto, permite modificar las entradas de la lista.

Comentarios

Puede usar GetPrev en un bucle de iteración inversa si establece la posición inicial con una llamada a GetTailPosition o Find.

Debe asegurarse de que el valor POSITION representa una posición válida en la lista. Si no es válida, se impone la versión de depuración de la biblioteca MFC (Microsoft Foundation Class).

Si el elemento recuperado es el primero de la lista, el valor nuevo de rPosition se establece en NULL.

Ejemplo

// Define myList.
CList<CString,CString&> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Dump the list elements to the debug window,
// in reverse order.
POSITION pos = myList.GetTailPosition();
for (int i = 0; i < myList.GetCount(); i++)
{
   TRACE(_T("%s\r\n"), (LPCTSTR)myList.GetPrev(pos));
}

CList::GetSize

Devuelve el número de elementos de lista.

INT_PTR GetSize() const;

Valor devuelto

El número de elementos de la lista.

Comentarios

Llame a este método para recuperar el número de elementos de la lista. Al llamar a este método, se generará el mismo resultado que con el método CList::GetCount.

Ejemplo

// Define myList.
CList<CString, CString &> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Remove the head element and verify the list.
// NOTE: once the head is removed, the number of
// elements in the list will be one.
CString strHead = myList.RemoveHead();
ASSERT((CString(_T("123")) == strHead) && (myList.GetSize() == 1) &&
       (CString(_T("ABC")) == myList.GetHead()));

CList::GetTail

Obtiene el puntero CObject que representa el elemento del final de esta lista.

TYPE& GetTail();
const TYPE& GetTail() const;

Parámetros

TYPE
Parámetro de plantilla que especifica el tipo de elementos de la lista.

Valor devuelto

Consulte la descripción del valor devuelto para GetHead.

Comentarios

Debe asegurarse de que la lista no esté vacía antes de llamar a GetTail. Si lo está, se impone la versión de depuración de la biblioteca MFC (Microsoft Foundation Class). Use IsEmpty para comprobar que la lista contiene elementos.

Ejemplo

// Define myList.
CList<CString, CString &> myList;

// Add an element to the end of the list.
myList.AddTail(CString(_T("ABC")));

// Verify the element was added to the end of the list.
ASSERT(CString(_T("ABC")) == myList.GetTail());

CList::GetTailPosition

Obtiene la posición del elemento del final de esta lista; NULL si la lista está vacía.

POSITION GetTailPosition() const;

Valor devuelto

Valor POSITION que se puede usar para la recuperación de puntero de objeto o iteración; NULL si la lista está vacía.

Ejemplo

// Define myList.
CList<CString,CString&> myList;

// Add an element to the end of the list.
myList.AddTail(CString(_T("ABC")));

// Verify the element at the end position
// is the one added.
POSITION pos = myList.GetTailPosition();
ASSERT(CString(_T("ABC")) == myList.GetAt(pos));      

CList::InsertAfter

Agrega un elemento a esta lista después del elemento en la posición especificada.

POSITION InsertAfter(POSITION position, ARG_TYPE newElement);

Parámetros

position
Un valor POSITION devuelto por una llamada de función miembro GetNext, GetPrev o Find.

ARG_TYPE
Parámetro de plantilla que especifica el tipo del elemento de lista.

newElement
Elemento que se va a agregar a esta lista.

Valor devuelto

Valor POSITION que puede usarse para la recuperación de elementos de lista o iteración.

Ejemplo

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
POSITION pos = myList.AddHead(CString(_T("XYZ")));
pos = myList.InsertAfter(pos, CString(_T("ABC")));
pos = myList.InsertAfter(pos, CString(_T("123")));

// Verify the tail element is what's expected.
ASSERT(CString(_T("123")) == myList.GetTail());

CList::InsertBefore

Agrega un elemento a esta lista delante del elemento en la posición especificada.

POSITION InsertBefore(POSITION position, ARG_TYPE newElement);

Parámetros

position
Valor POSITION devuelto por una llama de función miembro anterior GetNext, GetPrev o Find.

ARG_TYPE
Parámetro de plantilla que especifica el tipo de elemento de lista (puede ser una referencia).

newElement
Elemento que se va a agregar a esta lista.

Valor devuelto

Valor POSITION que puede usarse para la recuperación de elementos de lista o iteración.

Comentarios

Si position es NULL, el elemento se inserta en el encabezado de la lista.

Ejemplo

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
POSITION pos = myList.AddHead(CString(_T("XYZ")));
pos = myList.InsertBefore(pos, CString(_T("ABC")));
pos = myList.InsertBefore(pos, CString(_T("123")));

// Verify the head element is what's expected.
ASSERT(CString(_T("123")) == myList.GetHead());

CList::IsEmpty

Indica si esta lista no contiene ningún elemento.

BOOL IsEmpty() const;

Valor devuelto

Distinto de cero si esta lista está vacía; de lo contrario, 0.

Ejemplo

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove the head element until the list is empty.
CString str;
while (!myList.IsEmpty())
{
   str = myList.RemoveHead();
   TRACE(_T("%s\r\n"), (LPCTSTR)str);
}

CList::RemoveAll

Quita todos los elementos de esta lista y libera la memoria asociada.

void RemoveAll();

Comentarios

No se genera ningún error si la lista ya está vacía.

Ejemplo

// Define myList.
CList<CString, CString&> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove all of the elements in the list.
myList.RemoveAll();

// Verify the list is empty.
ASSERT(myList.IsEmpty());

CList::RemoveAt

Quita el elemento especificado de esta lista.

void RemoveAt(POSITION position);

Parámetros

position
Posición del elemento que se va a quitar de la lista.

Comentarios

Debe asegurarse de que el valor POSITION representa una posición válida en la lista. Si no es válida, se impone la versión de depuración de la biblioteca MFC (Microsoft Foundation Class).

Ejemplo

// Define myList.
CList<CString, CString&> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove CString("ABC") from the list.
myList.RemoveAt(myList.FindIndex(1));

// Verify CString("ABC") is not in the list.
ASSERT(myList.Find(CString(_T("ABC"))) == NULL);

CList::RemoveHead

Quita el elemento del encabezado de la lista y devuelve un puntero a él.

TYPE RemoveHead();

Parámetros

TYPE
Parámetro de plantilla que especifica el tipo de elementos de la lista.

Valor devuelto

Elemento que anteriormente se encontraba en el encabezado de la lista.

Comentarios

Debe asegurarse de que la lista no esté vacía antes de llamar a RemoveHead. Si lo está, se impone la versión de depuración de la biblioteca MFC (Microsoft Foundation Class). Use IsEmpty para comprobar que la lista contiene elementos.

Ejemplo

// Define myList.
CList<CString, CString&> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Remove the head element and verify the list.
// NOTE: once the head is removed, the number of
// elements in the list will be one.
CString strHead = myList.RemoveHead();
ASSERT((CString(_T("123")) == strHead) && (myList.GetCount() == 1) &&
(CString(_T("ABC")) == myList.GetHead()));

CList::RemoveTail

Quita el elemento de la cola de la lista y devuelve un puntero a él.

TYPE RemoveTail();

Parámetros

TYPE
Parámetro de plantilla que especifica el tipo de elementos de la lista.

Valor devuelto

Elemento que se encontraba en el final de la lista.

Comentarios

Debe asegurarse de que la lista no esté vacía antes de llamar a RemoveTail. Si lo está, se impone la versión de depuración de la biblioteca MFC (Microsoft Foundation Class). Use IsEmpty para comprobar que la lista contiene elementos.

Ejemplo

// Define myList.
CList<CString, CString &> myList;

// Add two elements to the list.
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove the tail element and verify the list.
// NOTE: once the tail is removed, the number of
// elements in the list will be one.
CString strTail = myList.RemoveTail();
ASSERT((CString(_T("123")) == strTail) && (myList.GetCount() == 1) &&
       (CString(_T("ABC")) == myList.GetTail()));

CList::SetAt

Una variable de tipo POSITION es una clave para la lista.

void SetAt(POSITION pos, ARG_TYPE newElement);

Parámetros

pos
POSITION del elemento que se va a establecer.

ARG_TYPE
Parámetro de plantilla que especifica el tipo de elemento de lista (puede ser una referencia).

newElement
Elemento que se va a agregar a la lista.

Comentarios

No es lo mismo que un índice y no puede trabajar usted mismo con un valor POSITION. SetAt escribe el elemento en la posición especificada de la lista.

Debe asegurarse de que el valor POSITION representa una posición válida en la lista. Si no es válida, se impone la versión de depuración de la biblioteca MFC (Microsoft Foundation Class).

Ejemplo

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Replace CString("ABC") with CString("CBA")
POSITION pos = myList.Find(CString(_T("ABC")));
myList.SetAt(pos, CString(_T("CBA")));

// Verify CString("ABC") is not in the list.
ASSERT(myList.Find(CString(_T("ABC"))) == NULL);

Consulte también

Ejemplo de MFCCOLLECT
CObject (clase)
Gráfico de jerarquías
CMap (clase)
CArray (clase)