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
CList
Requisitos
Encabezado: afxtempl.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);
Vea también
Ejemplo de MFCCOLLECT
CObject
(clase)
Gráfico de jerarquías
CMap
(clase)
CArray
(clase)