ATL Collection Classes


The new home for Visual Studio documentation is Visual Studio 2017 Documentation on

The latest version of this topic can be found at ATL Collection Classes.

ATL provides many classes for storing and accessing data. Which class you decide to use depends on several factors, including:

  • The amount of data to be stored

  • Efficiency versus performance in accessing the data

  • The ability to access the data by index or by key

  • How the data is ordered

  • Personal preference

ATL provides the following array classes for dealing with small numbers of objects. However, these classes are limited and designed for use internally by ATL. It is not recommended that you use them in your programs.

ClassType of data storage
CSimpleArrayImplements an array class for dealing with small numbers of objects.
CSimpleMapImplements a mapping class for dealing with small numbers of objects.

The follow classes implement arrays, lists, and maps and are provided as general purpose collection classes:

ClassType of data storage
CAtlArrayImplements an array.
CAtlListImplements a list.
CAtlMapImplements a mapping structure, whereby data can be referenced by key or value.
CRBMapImplements a mapping structure using the Red-Black algorithm.
CRBMultiMapImplements a Red-Black multimapping structure.

These classes will trap many programming errors when used in debug builds, but for sake of performance, these checks will not be performed in retail builds.

More specialized collection classes are also provided for managing memory pointers and interface pointers:

CAutoPtrArrayProvides methods useful when constructing an array of smart pointers.
CAutoPtrListProvides methods useful when constructing a list of smart pointers.
CComUnkArrayStores IUnknown pointers and is designed to be used as a parameter to the IConnectionPointImpl template class.
CHeapPtrListProvides methods useful when constructing a list of heap pointers.
CInterfaceArrayProvides methods useful when constructing an array of COM interface pointers.
CInterfaceListProvides methods useful when constructing a list of COM interface pointers.

Each of the available collection classes offers different performance characteristics, as shown in the table below.

  • Columns 2 and 3 describe each class's ordering and access characteristics. In the table, the term "ordered" means that the order in which items are inserted and deleted determines their order in the collection; it does not mean the items are sorted on their contents. The term "indexed" means that the items in the collection can be retrieved by an integer index, much like items in a typical array.

  • Columns 4 and 5 describe each class's performance. In applications that require many insertions into the collection, insertion speed might be especially important; for other applications, lookup speed may be more important.

  • Column 6 describes whether each shape allows duplicate elements.

  • The performance of a given collection class operation is expressed in terms of the relationship between the time required to complete the operation and the number of elements in the collection. An operation taking an amount of time that increases linearly as the number of elements increases is described as an O(n) algorithm. By contrast, an operation taking a period of time that increases less and less as the number of elements increases is described as an O(log n) algorithm. Therefore, in terms of performance, O(log n) algorithms outperform O(n) algorithms more and more as the number of elements increases.

Collection Shape Features

ShapeOrderedIndexedInsert an

Search for

specified element

ListYesNoFast (constant time)Slow O(n)Yes
ArrayYesBy int (constant time)Slow O(n) except if inserting at end, in which case constant timeSlow O(n)Yes
MapNoBy key (constant time)Fast (constant time)Fast (constant time)No (keys) Yes (values)
Red-Black MapYes (by key)By key O(log n)Fast O(log n)Fast O(log n)No
Red-Black MultimapYes (by key)By key O(log n) (multiple values per key)Fast O(log n)Fast O(log n)Yes (multiple values per key)

As the ATL collection classes can be used to store a wide range of user-defined data types, it can be useful to be able to override important functions such as comparisons. This is achieved using the CTraits classes.

CTraits classes are similar to, but more flexible than, the MFC collection class helper functions; see Collection Class Helpers for more information.

When constructing your collection class, you have the option of specifying a CTraits class. This class will contain the code that will perform operations such as comparisons when called by the other methods that make up the collection class. For example, if your list object contains your own user-defined structures, you may want to redefine the equality test to only compare certain member variables. In this way, the list object's Find method will operate in a more useful manner.


// Collection class / traits class example.
// This program demonstrates using a CTraits class
// to create a new comparison operator.

#define MAX_STRING 80

// Define our own data type to store in the list.

struct MyData 
   int ID;
   TCHAR address[MAX_STRING];

// Define our own traits class, making use of the
// existing traits and overriding only the comparison
// we need.

class MyTraits : public CElementTraits< MyData >
    // Override the comparison to only compare
    // the ID value.

   static bool CompareElements(const MyData& element1, const MyData& element2)
      if (element1.ID == element2.ID)
         return true;
         return false;

void DoAtlCustomTraitsList()
   // Declare the array, with our data type and traits class 

   CAtlList < MyData, MyTraits > MyList;

   // Create some variables of our data type

   MyData add_item, search_item;

   // Add some elements to the list.

   add_item.ID = 1;
   _stprintf_s(, _T("Rumpelstiltskin"));
   _stprintf_s(add_item.address, _T("One Grimm Way"));


   add_item.ID = 2;
   _stprintf_s(, _T("Rapunzel"));
   _stprintf_s(add_item.address, _T("One Grimm Way"));


   add_item.ID = 3;
   _stprintf_s(, _T("Cinderella"));
   _stprintf_s(add_item.address, _T("Two Grimm Way"));


   // Create an element which will be used
   // to search the list for a match.

   search_item.ID = 2;
   _stprintf_s(, _T("Don't care"));
   _stprintf_s(search_item.address, _T("Don't care"));

   // Perform a comparison by searching for a match
   // between any element in the list, and our
   // search item. This operation will use the
   // (overridden) comparison operator and will
   // find a match when the IDs are the same.


   i = MyList.Find(search_item);

   if (i != NULL)
      _tprintf_s(_T("Item found!\n"));
      _tprintf_s(_T("Item not found.\n"));

For a list of the CTraits classes, see Collection Classes.

The following diagram shows the class hierarchy for the CTraits classes.

Traits hierarchy for collection classes

The following samples demonstrate the collection classes:

Collection Classes