ceph/src/boost/libs/range/doc/mfc_atl.rst

   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