98ba1eee5d
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52096 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
72 lines
3.6 KiB
C
72 lines
3.6 KiB
C
/////////////////////////////////////////////////////////////////////////////
|
|
// Name: container.h
|
|
// Purpose: topic overview
|
|
// Author: wxWidgets team
|
|
// RCS-ID: $Id$
|
|
// Licence: wxWindows license
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
/*!
|
|
|
|
@page overview_container Container classes overview
|
|
|
|
Classes: wxList<T>, wxArray<T>, wxVector<T>
|
|
|
|
wxWidgets uses itself several container classes including doubly-linked lists
|
|
and dynamic arrays (i.e. arrays which expand automatically when they become
|
|
full). For both historical and portability reasons wxWidgets does not use STL
|
|
which provides the standard implementation of many container classes in C++.
|
|
|
|
First of all, wxWidgets has existed since well before STL was written, and
|
|
secondly we don't believe that today compilers can deal really well with all of
|
|
STL classes (this is especially true for some less common platforms). Of
|
|
course, the compilers are evolving quite rapidly and hopefully their progress
|
|
will allow to base future versions of wxWidgets on STL - but this is not yet
|
|
the case.
|
|
|
|
wxWidgets container classes don't pretend to be as powerful or full as STL
|
|
ones, but they are quite useful and may be compiled with absolutely any C++
|
|
compiler. They're used internally by wxWidgets, but may, of course, be used in
|
|
your programs as well if you wish.
|
|
|
|
The list classes in wxWidgets are doubly-linked lists which may either own the
|
|
objects they contain (meaning that the list deletes the object when it is
|
|
removed from the list or the list itself is destroyed) or just store the
|
|
pointers depending on whether you called or not wxList::DeleteContents method.
|
|
|
|
Dynamic arrays resemble C arrays but with two important differences: they
|
|
provide run-time range checking in debug builds and they automatically expand
|
|
the allocated memory when there is no more space for new items. They come in
|
|
two sorts: the "plain" arrays which store either built-in types such as "char",
|
|
"int" or "bool" or the pointers to arbitrary objects, or "object arrays" which
|
|
own the object pointers to which they store.
|
|
|
|
For the same portability reasons, the container classes implementation in wxWidgets
|
|
does not use templates, but is rather based on C preprocessor i.e. is done with
|
|
the macros: @e WX_DECLARE_LIST and @e WX_DEFINE_LIST for the linked
|
|
lists and @e WX_DECLARE_ARRAY, @e WX_DECLARE_OBJARRAY and @e WX_DEFINE_OBJARRAY for
|
|
the dynamic arrays.
|
|
|
|
The "DECLARE" macro declares a new container class containing the elements of
|
|
given type and is needed for all three types of container classes: lists,
|
|
arrays and objarrays. The "DEFINE" classes must be inserted in your program
|
|
in a place where the @b full declaration of container element class is in scope
|
|
(i.e. not just forward declaration), otherwise destructors of the container
|
|
elements will not be called!
|
|
|
|
As array classes never delete the items they contain anyhow, there is
|
|
no WX_DEFINE_ARRAY macro for them.
|
|
|
|
Examples of usage of these macros may be found in wxList and wxArray documentation.
|
|
|
|
Finally, wxWidgets predefines several commonly used container classes. wxList
|
|
is defined for compatibility with previous versions as a list containing
|
|
wxObjects and wxStringList as a list of C-style strings (char *), both of these
|
|
classes are deprecated and should not be used in new programs. The following
|
|
array classes are defined: wxArrayInt, wxArrayLong, wxArrayPtrVoid and
|
|
wxArrayString. The first three store elements of corresponding types, but
|
|
wxArrayString is somewhat special: it is an optimized version of wxArray which
|
|
uses its knowledge about wxString reference counting schema.
|
|
|
|
*/
|