The STL is a very useful addition to the C++ language and it is really not that hard to learn and it will make your life easier I promise.

This article shows how to use a very useful STL class, the list. There are lots of occasions when you might need to make a variable-length list or queue or stack, the list container can be used for all of those things.

I am not going to waste your time with theory, lets just get straight onto some practical examples.

First include the header file. Note that STL headers do not have .h after them.

#include <list>

Now to create a list. You can create a list of any type of object (they do get tricky with polymorphic objects but ordinary primitives and classes are dead easy). To create a list of integers for example, just do this:

std::list<int> MyList;

But that example is too trivial. In real life, you will most likely want to make lists of your own classes so lets make up a class called Person to store someone’s name:

class Person
{
public:
    Person(const char *firstName, const char *lastName)
        : _first(firstName)
        , _last(lastName)
    { }

    void printName() const { std::cout << _first << " " << _last << std::endl; }

private:
    std::string _first;
    std::string _last;
};

Now we can define a list of them. You don’t have to do it using typedef but in my experience it will save you some pain. Trust me on this one.

typedef std::list<Person> PERSONLIST;

Then create an instance of the list:

PERSONLIST myFriends;

Next you need to know how to insert items into the list. A good way is to use the push_back function:

myFriends.push_back(Person("Adam", "Pierce"));

Finally you will need to know how to extract items from the list. The most common type of access would be to create a loop which iterates over the whole list. STL provides an iterator which you can place into a for loop. This example uses an iterator to print out every item in the list:

    for(PERSONLIST::const_iterator it = myFriends.begin(); it != myFriends.end(); it++)
    {
        (*it).printName();
    }

And that is pretty much it for STL lists. How easy was that! Or more correctly, how many lines of code would you have to write and debug to create your own linked list and how much time would that take ?

There is a lot more to the STL of course and even a lot more to lists (for example, I have not covered how to remove items from a list), but the intention of this article was to give you a small taste of how STL containers work. Even if you only use the list container in this simple way you will find it speeds up your development times.

To finish up, I will put together the previous examples into a working program that prints a list of my friends (hmm, I don’t seem to have very many do I).

// *********************************************************************
// ** Simple STL container example by Adam Pierce <adam@doctort.org>
// **

#include <list> // We will be using the STL list class.
#include <string> // We will be using C++ strings.
#include <iostream> // We will be using cout to print to the standard output.

using namespace std; // This is optional but it does make the code look neater.

// This class can store the name of one person.
class Person
{
public:
    Person(const char *firstName, const char *lastName)
        : _first(firstName)
        , _last(lastName)
    { }

    void print() const { cout << _first << " " << _last << endl; }

private:
    string _first;
    string _last;
};

// Now we define PERSONLIST which is a list of Persons.
typedef list<Person> PERSONLIST;

main()
{
// Create an empty list.
    PERSONLIST myFriends;

// Populate the list.
    myFriends.push_back(Person("Jasper","Russell"));
    myFriends.push_back(Person("Mike","Cornelius"));
    myFriends.push_back(Person("James","McParlane"));

// Print the list.
    cout << "A list of my friends:" << endl;
    for(PERSONLIST::const_iterator it = myFriends.begin(); it != myFriends.end(); it++)
        (*it).print();

    return 0;
}