X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b8afbac6aa1359906b9926794d6573d6e052afb7..2e18fe7139558b3cb592a04a4e4668319a966ebf:/docs/doxygen/overviews/container.h diff --git a/docs/doxygen/overviews/container.h b/docs/doxygen/overviews/container.h index 5c7dc2b2cd..eaf176e733 100644 --- a/docs/doxygen/overviews/container.h +++ b/docs/doxygen/overviews/container.h @@ -3,69 +3,128 @@ // Purpose: topic overview // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// -/*! - - @page overview_container Container classes overview - - Classes: #wxList, #wxArray, #wxVector - - 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. +/** + +@page overview_container Container Classes + +Classes: wxList, wxArray, wxVector, wxStack, wxHashMap, wxHashSet + +@section overview_container_intro Overview + +For historical reasons, wxWidgets uses custom container classes internally. +This was unfortunately unavoidable during a long time when the standard library +wasn't widely available and can't be easily changed even now that it is for +compatibility reasons. If you are building your own version of the library and +don't care about compatibility nor slight (less than 5%) size penalty imposed +by the use of STL classes, you may choose to use the "STL" build of wxWidgets +in which these custom classes are replaced with their standard counterparts and +only read the section @ref overview_container_std explaining how to do it. + +Otherwise you will need to know about the custom wxWidgets container classes +such as wxList and wxArray if only to use wxWidgets functions that work +with them, e.g. wxWindow::GetChildren(), and you should find the information +about using these classes below useful. + +Notice that we recommend that you use standard classes directly in your own +code instead of the container classes provided by wxWidgets in any case as the +standard classes are easier to use and may also be safer because of extra +run-time checks they may perform as well as more efficient. + +Finally notice that recent versions of wxWidgets also provide standard-like +classes such as wxVector, wxStack or wxDList which can be used exactly +like the std::vector, std::stack and std::list, respectively, and +actually are just typedefs for the corresponding types if wxWidgets is compiled +in STL mode. These classes could be useful if you wish to avoid the use of the +standard library in your code for some reason. + +To summarize, you should use the standard container classes such as +std::vector and std::list if possible and wxVector or wxDList if +it isn't and only use legacy wxWidgets containers such as wxArray and +wxList when you must, i.e. when you use a wxWidgets function taking or +returning a container of such type. + + +@section overview_container_legacy Legacy Classes + +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 or not you called 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 don't use templates, but are rather based on C preprocessor i.e. are +implemented using the macros: WX_DECLARE_LIST() and WX_DEFINE_LIST() for the +linked lists and WX_DECLARE_ARRAY(), WX_DECLARE_OBJARRAY() and +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 @e 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. + + +@section overview_container_std STL Build + +To build wxWidgets with the standard containers you need to set +wxUSE_STD_CONTAINERS option to 1 in @c wx/msw/setup.h for wxMSW builds or +specify @c --enable-std_containers option to configure (which is also +implicitly enabled by @c --enable-stl option) in Unix builds. + +The standard container build is mostly, but not quite, compatible with the +default one. Here are the most important differences: + - wxList::compatibility_iterator must be used instead of wxList::Node* when + iterating over the list contents. The compatibility_iterator class has the + same semantics as a Node pointer but it is an object and not a pointer, so + you need to write + @code + for ( wxWindowList::compatibility_iterator it = list.GetFirst(); + it; + it = it->GetNext() ) + ... + @endcode + instead of the old + @code + for ( wxWindowList::Node *n = list.GetFirst(); n; n = n->GetNext() ) + ... + @endcode + - wxSortedArrayString and wxArrayString are separate classes now and the + former doesn't derive from the latter. If you need to convert a sorted array + to a normal one, you must copy all the elements. Alternatively, you may + avoid the use of wxSortedArrayString by using a normal array and calling its + Sort() method when needed. + - WX_DEFINE_ARRAY_INT(bool) cannot be used because of the differences in + std::vector specialization compared with the generic std::vector<> + class. Please either use std::vector directly or use an integer array + instead. + */ +