[ceph.git] / ceph / src / boost / libs / range / doc / mfc_atl.rst


++++++++++++++++++++++++++++++++
 |Boost| Range MFC/ATL Extension
++++++++++++++++++++++++++++++++

.. |Boost| image:: http://www.boost.org/libs/ptr_container/doc/boost.png


:Author:        Shunsuke Sogame
:Contact:       mb2act@yahoo.co.jp
:date:          26th of May 2006
:copyright:     Shunsuke Sogame 2005-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).

__ http://www.boost.org/LICENSE_1_0.txt


========
Overview
========

Boost.Range MFC/ATL Extension provides `Boost.Range`_ support for MFC/ATL collection and string types.


.. parsed-literal::

        CTypedPtrArray<CPtrArray, CList<CString> \*> myArray;
        ...
        BOOST_FOREACH (CList<CString> \*theList, myArray)
        {
            BOOST_FOREACH (CString& str, \*theList)
            {
                boost::to_upper(str);
                std::sort(boost::begin(str), boost::end(str));
                ...
            }
        }


* `Requirements`_
* `MFC Ranges`_
* `ATL Ranges`_
* `const Ranges`_
* `References`_


============
Requirements
============

- `Boost C++ Libraries Version 1.34.0`__ or later (no compilation required)
- Visual C++ 7.1 or Visual C++ 8.0

__ Boost_


==========
MFC Ranges
==========

If the ``<boost/range/mfc.hpp>`` is included before or after `Boost.Range`_ headers,
the MFC collections and strings become models of Range.
The table below lists the Traversal Category and ``range_reference`` of MFC ranges.


============================= ================== =======================================
``Range``                     Traversal Category ``range_reference<Range>::type``
============================= ================== =======================================
``CArray<T,A>``               Random Access      ``T&``
----------------------------- ------------------ ---------------------------------------
``CList<T,A>``                Bidirectional      ``T&``
----------------------------- ------------------ ---------------------------------------
``CMap<K,AK,M,AM>``           Forward            ``Range::CPair&``
----------------------------- ------------------ ---------------------------------------
``CTypedPtrArray<B,T*>``      Random Access      ``T* const``
----------------------------- ------------------ ---------------------------------------
``CTypedPtrList<B,T*>``       Bidirectional      ``T* const``
----------------------------- ------------------ ---------------------------------------
``CTypedPtrMap<B,T*,V*>``     Forward            ``std::pair<T*,V*> const``
----------------------------- ------------------ ---------------------------------------
``CByteArray``                Random Access      ``BYTE&``
----------------------------- ------------------ ---------------------------------------
``CDWordArray``               Random Access      ``DWORD&``
----------------------------- ------------------ ---------------------------------------
``CObArray``                  Random Access      ``CObject* &``
----------------------------- ------------------ ---------------------------------------
``CPtrArray``                 Random Access      ``void* &``
----------------------------- ------------------ ---------------------------------------
``CStringArray``              Random Access      ``CString&``
----------------------------- ------------------ ---------------------------------------
``CUIntArray``                Random Access      ``UINT&``
----------------------------- ------------------ ---------------------------------------
``CWordArray``                Random Access      ``WORD&``
----------------------------- ------------------ ---------------------------------------
``CObList``                   Bidirectional      ``CObject* &``
----------------------------- ------------------ ---------------------------------------
``CPtrList``                  Bidirectional      ``void* &``
----------------------------- ------------------ ---------------------------------------
``CStringList``               Bidirectional      ``CString&``
----------------------------- ------------------ ---------------------------------------
``CMapPtrToWord``             Forward            ``std::pair<void*,WORD> const``
----------------------------- ------------------ ---------------------------------------
``CMapPtrToPtr``              Forward            ``std::pair<void*,void*> const``
----------------------------- ------------------ ---------------------------------------
``CMapStringToOb``            Forward            ``std::pair<String,CObject*> const``
----------------------------- ------------------ ---------------------------------------
``CMapStringToString``        Forward            ``Range::CPair&``
----------------------------- ------------------ ---------------------------------------
``CMapWordToOb``              Forward            ``std::pair<WORD,CObject*> const``
----------------------------- ------------------ ---------------------------------------
``CMapWordToPtr``             Forward            ``std::pair<WORD,void*> const``
============================= ================== =======================================


Other `Boost.Range`_ metafunctions are defined by the following.
Let ``Range`` be any type listed above and ``ReF`` be the same as ``range_reference<Range>::type``.
``range_value<Range>::type`` is the same as ``remove_reference<remove_const<Ref>::type>::type``,
``range_difference<Range>::type`` is the same as ``std::ptrdiff_t``, and
``range_pointer<Range>::type`` is the same as ``add_pointer<remove_reference<Ref>::type>::type``.
As for ``const Range``, see `const Ranges`_.


==========
ATL Ranges
==========

If the ``<boost/range/atl.hpp>`` is included before or after `Boost.Range`_ headers,
the ATL collections and strings become models of Range.
The table below lists the Traversal Category and ``range_reference`` of ATL ranges.


============================= ================== =======================================
``Range``                     Traversal Category ``range_reference<Range>::type``
============================= ================== =======================================
``CAtlArray<E,ET>``           Random Access      ``E&``
----------------------------- ------------------ ---------------------------------------
``CAutoPtrArray<E>``          Random Access      ``E&``
----------------------------- ------------------ ---------------------------------------
``CInterfaceArray<I,pi>``     Random Access      ``CComQIPtr<I,pi>&``
----------------------------- ------------------ ---------------------------------------
``CAtlList<E,ET>``            Bidirectional      ``E&``
----------------------------- ------------------ ---------------------------------------
``CAutoPtrList<E>``           Bidirectional      ``E&``
----------------------------- ------------------ ---------------------------------------
``CHeapPtrList<E,A>``         Bidirectional      ``E&``
----------------------------- ------------------ ---------------------------------------
``CInterfaceList<I,pi>``      Bidirectional      ``CComQIPtr<I,pi>&``
----------------------------- ------------------ ---------------------------------------
``CAtlMap<K,V,KT,VT>``        Forward            ``Range::CPair&``
----------------------------- ------------------ ---------------------------------------
``CRBTree<K,V,KT,VT>``        Bidirectional      ``Range::CPair&``
----------------------------- ------------------ ---------------------------------------
``CRBMap<K,V,KT,VT>``         Bidirectional      ``Range::CPair&``
----------------------------- ------------------ ---------------------------------------
``CRBMultiMap<K,V,KT,VT>``    Bidirectional      ``Range::CPair&``
----------------------------- ------------------ ---------------------------------------
``CSimpleStringT<B,b>``       Random Access      ``B&``
----------------------------- ------------------ ---------------------------------------
``CStringT<B,ST>``            Random Access      ``B&``
----------------------------- ------------------ ---------------------------------------
``CFixedStringT<S,n>``        Random Access      ``range_reference<S>::type``
----------------------------- ------------------ ---------------------------------------
``CStringT<B,ST>``            Random Access      ``B&``
----------------------------- ------------------ ---------------------------------------
``CComBSTR``                  Random Access      ``OLECHAR&``
----------------------------- ------------------ ---------------------------------------
``CSimpleArray<T,TE>``        Random Access      ``T&``
============================= ================== =======================================


Other `Boost.Range`_ metafunctions are defined by the following.
Let ``Range`` be any type listed above and ``ReF`` be the same as ``range_reference<Range>::type``.
``range_value<Range>::type`` is the same as ``remove_reference<Ref>::type``,
``range_difference<Range>::type`` is the same as ``std::ptrdiff_t``, and
``range_pointer<Range>::type`` is the same as ``add_pointer<remove_reference<Ref>::type>::type``.
As for ``const Range``, see `const Ranges`_.


============
const Ranges
============

``range_reference<const Range>::type`` is defined by the following algorithm.
Let ``Range`` be any type listed above and ``ReF`` be the same as ``range_reference<Range>::type``.


.. parsed-literal::

    if (Range is CObArray || Range is CObList)
        return CObject const \* &
    else if (Range is CPtrArray || Range is CPtrList)
        return void const \* &
    else if (there is a type X such that X& is the same as ReF)
        return X const &
    else if (there is a type X such that X* const is the same as ReF)
        return X const \* const
    else
        return ReF


Other `Boost.Range`_ metafunctions are defined by the following.
``range_value<const Range>::type`` is the same as ``range_value<Range>::type``,
``range_difference<const Range>::type`` is the same as ``std::ptrdiff_t``, and
``range_pointer<const Range>::type`` is the same as ``add_pointer<remove_reference<range_reference<const Range>::type>::type>::type``.


==========
References
==========
- `Boost.Range`_
- `MFC Collections`__
- `ATL Collection Classes`__

__ http://msdn2.microsoft.com/en-us/library/942860sh.aspx
__ http://msdn2.microsoft.com/en-US/library/15e672bd.aspx


.. _Boost C++ Libraries: http://www.boost.org/
.. _Boost: `Boost C++ Libraries`_
.. _Boost.Range: ../index.html
.. _forward: range.html#forward_range
.. _bidirectional: range.html#forward_range
.. _random access: range.html#random_access_range
Commit	Line	Data
7c673cae FG	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	========
	20	Overview
	21	========
	22
	23	Boost.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	============
	51	Requirements
	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	==========
	62	MFC Ranges
	63	==========
	64
65	If the ``<boost/range/mfc.hpp>`` is included before or after `Boost.Range`_ headers,
66	the MFC collections and strings become models of Range.
67	The 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
119	Other `Boost.Range`_ metafunctions are defined by the following.
120	Let ``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``.
124	As for ``const Range``, see `const Ranges`_.
125
126
127
128	==========
129	ATL Ranges
130	==========
131
132	If the ``<boost/range/atl.hpp>`` is included before or after `Boost.Range`_ headers,
133	the ATL collections and strings become models of Range.
134	The 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
176	Other `Boost.Range`_ metafunctions are defined by the following.
177	Let ``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``.
181	As for ``const Range``, see `const Ranges`_.
182
183
184
185	============
186	const Ranges
187	============
188
189	``range_reference<const Range>::type`` is defined by the following algorithm.
190	Let ``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
207	Other `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	==========
215	References
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