1
2++++++++++++++++++++++++++++++++
3 |Boost| Range MFC/ATL Extension
4++++++++++++++++++++++++++++++++
5
6.. |Boost| image:: http://www.boost.org/libs/ptr_container/doc/boost.png
7
8
9
10:Author:        Shunsuke Sogame
11:Contact:       mb2act@yahoo.co.jp
12:date:          26th of May 2006
13:copyright:     Shunsuke Sogame 2005-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).
14
15__ http://www.boost.org/LICENSE_1_0.txt
16
17
18
19========
20Overview
21========
22
23Boost.Range MFC/ATL Extension provides `Boost.Range`_ support for MFC/ATL collection and string types.
24
25
26.. parsed-literal::
27
28        CTypedPtrArray<CPtrArray, CList<CString> \*> myArray;
29        ...
30        BOOST_FOREACH (CList<CString> \*theList, myArray)
31        {
32            BOOST_FOREACH (CString& str, \*theList)
33            {
34                boost::to_upper(str);
35                std::sort(boost::begin(str), boost::end(str));
36                ...
37            }
38        }
39
40
41
42* `Requirements`_
43* `MFC Ranges`_
44* `ATL Ranges`_
45* `const Ranges`_
46* `References`_
47
48
49
50============
51Requirements
52============
53
54- `Boost C++ Libraries Version 1.34.0`__ or later (no compilation required)
55- Visual C++ 7.1 or Visual C++ 8.0
56
57__ Boost_
58
59
60
61==========
62MFC Ranges
63==========
64
65If the ``<boost/range/mfc.hpp>`` is included before or after `Boost.Range`_ headers,
66the MFC collections and strings become models of Range.
67The table below lists the Traversal Category and ``range_reference`` of MFC ranges.
68
69
70============================= ================== =======================================
71``Range``                     Traversal Category ``range_reference<Range>::type``
72============================= ================== =======================================
73``CArray<T,A>``               Random Access      ``T&``
74----------------------------- ------------------ ---------------------------------------
75``CList<T,A>``                Bidirectional      ``T&``
76----------------------------- ------------------ ---------------------------------------
77``CMap<K,AK,M,AM>``           Forward            ``Range::CPair&``
78----------------------------- ------------------ ---------------------------------------
79``CTypedPtrArray<B,T*>``      Random Access      ``T* const``
80----------------------------- ------------------ ---------------------------------------
81``CTypedPtrList<B,T*>``       Bidirectional      ``T* const``
82----------------------------- ------------------ ---------------------------------------
83``CTypedPtrMap<B,T*,V*>``     Forward            ``std::pair<T*,V*> const``
84----------------------------- ------------------ ---------------------------------------
85``CByteArray``                Random Access      ``BYTE&``
86----------------------------- ------------------ ---------------------------------------
87``CDWordArray``               Random Access      ``DWORD&``
88----------------------------- ------------------ ---------------------------------------
89``CObArray``                  Random Access      ``CObject* &``
90----------------------------- ------------------ ---------------------------------------
91``CPtrArray``                 Random Access      ``void* &``
92----------------------------- ------------------ ---------------------------------------
93``CStringArray``              Random Access      ``CString&``
94----------------------------- ------------------ ---------------------------------------
95``CUIntArray``                Random Access      ``UINT&``
96----------------------------- ------------------ ---------------------------------------
97``CWordArray``                Random Access      ``WORD&``
98----------------------------- ------------------ ---------------------------------------
99``CObList``                   Bidirectional      ``CObject* &``
100----------------------------- ------------------ ---------------------------------------
101``CPtrList``                  Bidirectional      ``void* &``
102----------------------------- ------------------ ---------------------------------------
103``CStringList``               Bidirectional      ``CString&``
104----------------------------- ------------------ ---------------------------------------
105``CMapPtrToWord``             Forward            ``std::pair<void*,WORD> const``
106----------------------------- ------------------ ---------------------------------------
107``CMapPtrToPtr``              Forward            ``std::pair<void*,void*> const``
108----------------------------- ------------------ ---------------------------------------
109``CMapStringToOb``            Forward            ``std::pair<String,CObject*> const``
110----------------------------- ------------------ ---------------------------------------
111``CMapStringToString``        Forward            ``Range::CPair&``
112----------------------------- ------------------ ---------------------------------------
113``CMapWordToOb``              Forward            ``std::pair<WORD,CObject*> const``
114----------------------------- ------------------ ---------------------------------------
115``CMapWordToPtr``             Forward            ``std::pair<WORD,void*> const``
116============================= ================== =======================================
117
118
119Other `Boost.Range`_ metafunctions are defined by the following.
120Let ``Range`` be any type listed above and ``ReF`` be the same as ``range_reference<Range>::type``.
121``range_value<Range>::type`` is the same as ``remove_reference<remove_const<Ref>::type>::type``,
122``range_difference<Range>::type`` is the same as ``std::ptrdiff_t``, and
123``range_pointer<Range>::type`` is the same as ``add_pointer<remove_reference<Ref>::type>::type``.
124As for ``const Range``, see `const Ranges`_.
125
126
127
128==========
129ATL Ranges
130==========
131
132If the ``<boost/range/atl.hpp>`` is included before or after `Boost.Range`_ headers,
133the ATL collections and strings become models of Range.
134The table below lists the Traversal Category and ``range_reference`` of ATL ranges.
135
136
137============================= ================== =======================================
138``Range``                     Traversal Category ``range_reference<Range>::type``
139============================= ================== =======================================
140``CAtlArray<E,ET>``           Random Access      ``E&``
141----------------------------- ------------------ ---------------------------------------
142``CAutoPtrArray<E>``          Random Access      ``E&``
143----------------------------- ------------------ ---------------------------------------
144``CInterfaceArray<I,pi>``     Random Access      ``CComQIPtr<I,pi>&``
145----------------------------- ------------------ ---------------------------------------
146``CAtlList<E,ET>``            Bidirectional      ``E&``
147----------------------------- ------------------ ---------------------------------------
148``CAutoPtrList<E>``           Bidirectional      ``E&``
149----------------------------- ------------------ ---------------------------------------
150``CHeapPtrList<E,A>``         Bidirectional      ``E&``
151----------------------------- ------------------ ---------------------------------------
152``CInterfaceList<I,pi>``      Bidirectional      ``CComQIPtr<I,pi>&``
153----------------------------- ------------------ ---------------------------------------
154``CAtlMap<K,V,KT,VT>``        Forward            ``Range::CPair&``
155----------------------------- ------------------ ---------------------------------------
156``CRBTree<K,V,KT,VT>``        Bidirectional      ``Range::CPair&``
157----------------------------- ------------------ ---------------------------------------
158``CRBMap<K,V,KT,VT>``         Bidirectional      ``Range::CPair&``
159----------------------------- ------------------ ---------------------------------------
160``CRBMultiMap<K,V,KT,VT>``    Bidirectional      ``Range::CPair&``
161----------------------------- ------------------ ---------------------------------------
162``CSimpleStringT<B,b>``       Random Access      ``B&``
163----------------------------- ------------------ ---------------------------------------
164``CStringT<B,ST>``            Random Access      ``B&``
165----------------------------- ------------------ ---------------------------------------
166``CFixedStringT<S,n>``        Random Access      ``range_reference<S>::type``
167----------------------------- ------------------ ---------------------------------------
168``CStringT<B,ST>``            Random Access      ``B&``
169----------------------------- ------------------ ---------------------------------------
170``CComBSTR``                  Random Access      ``OLECHAR&``
171----------------------------- ------------------ ---------------------------------------
172``CSimpleArray<T,TE>``        Random Access      ``T&``
173============================= ================== =======================================
174
175
176Other `Boost.Range`_ metafunctions are defined by the following.
177Let ``Range`` be any type listed above and ``ReF`` be the same as ``range_reference<Range>::type``.
178``range_value<Range>::type`` is the same as ``remove_reference<Ref>::type``,
179``range_difference<Range>::type`` is the same as ``std::ptrdiff_t``, and
180``range_pointer<Range>::type`` is the same as ``add_pointer<remove_reference<Ref>::type>::type``.
181As for ``const Range``, see `const Ranges`_.
182
183
184
185============
186const Ranges
187============
188
189``range_reference<const Range>::type`` is defined by the following algorithm.
190Let ``Range`` be any type listed above and ``ReF`` be the same as ``range_reference<Range>::type``.
191
192
193.. parsed-literal::
194
195    if (Range is CObArray || Range is CObList)
196        return CObject const \* &
197    else if (Range is CPtrArray || Range is CPtrList)
198        return void const \* &
199    else if (there is a type X such that X& is the same as ReF)
200        return X const &
201    else if (there is a type X such that X* const is the same as ReF)
202        return X const \* const
203    else
204        return ReF
205
206
207Other `Boost.Range`_ metafunctions are defined by the following.
208``range_value<const Range>::type`` is the same as ``range_value<Range>::type``,
209``range_difference<const Range>::type`` is the same as ``std::ptrdiff_t``, and
210``range_pointer<const Range>::type`` is the same as ``add_pointer<remove_reference<range_reference<const Range>::type>::type>::type``.
211
212
213
214==========
215References
216==========
217- `Boost.Range`_
218- `MFC Collections`__
219- `ATL Collection Classes`__
220
221__ http://msdn2.microsoft.com/en-us/library/942860sh.aspx
222__ http://msdn2.microsoft.com/en-US/library/15e672bd.aspx
223
224
225
226.. _Boost C++ Libraries: http://www.boost.org/
227.. _Boost: `Boost C++ Libraries`_
228.. _Boost.Range: ../index.html
229.. _forward: range.html#forward_range
230.. _bidirectional: range.html#forward_range
231.. _random access: range.html#random_access_range
232
233