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

[/
    Copyright 2010 Neil Groves
    Distributed under the Boost Software License, Version 1.0.
    (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
/]
[def __mfc_collections__ [@http://msdn.microsoft.com/en-us/library/942860sh.aspx MFC Collection Classes]]
[def __atl_collections__ [@http://msdn.microsoft.com/en-us/library/15e672bd.aspx ATL Collection Classes]]

[section:mfc_atl MFC/ATL (courtesy of Shunsuke Sogame)]

[h4 Introduction]
This implementation was kindly donated by Shunsuke Sogame. This header adapts MFC and ATL containers to the appropriate Range concepts.

[table
    []
    [[[*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]]
]

[h4 Overview]

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

``
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));
        ...
    }
}
``

[section:requirements Requirements]

* Boost C++ Libraries Version 1.34.0 or later (no compilation required)
* Visual C++ 7.1 or later (for MFC and ATL)

[endsect]

[section:mfc_ranges 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.

[table
    [[Range] [Traversal Category] [`range_reference<Range>::type`]]
    [[`CArray<T,A>`]           [__random_access_range__]   [`T&`]]
    [[`CList<T,A>`]            [__bidirectional_range__]   [`T&`]]
    [[`CMap<K,AK,M,AM>`]       [__forward_range__]         [`Range::CPair&`]]
    [[`CTypedPtrArray<B,T*>`]  [__random_access_range__]   [`T* const`]]
    [[`CTypedPtrList<B,T*>`]   [__bidirectional_range__]   [`T* const`]]
    [[`CTypedPtrMap<B,T*,V*>`] [__forward_range__]         [`std::pair<T*,V*> const`]]
    [[`CByteArray`]            [__random_access_range__]   [`BYTE&`]]
    [[`CDWordArray`]           [__random_access_range__]   [`DWORD&`]]
    [[`CObArray`]              [__random_access_range__]   [`CObject*&`]]
    [[`CPtrArray`]             [__random_access_range__]   [`void*&`]]
    [[`CStringArray`]          [__random_access_range__]   [`CString&`]]
    [[`CUIntArray`]            [__random_access_range__]   [`UINT&`]]
    [[`CWordArray`]            [__random_access_range__]   [`WORD&`]]
    [[`CObList`]               [__bidirectional_range__]   [`CObject*&`]]
    [[`CPtrList`]              [__bidirectional_range__]   [`void*&`]]
    [[`CStringList`]           [__bidirectional_range__]   [`CString&`]]
    [[`CMapPtrToWord`]         [__forward_range__]         [`std::pair<void*,WORD> const`]]
    [[`CMapPtrToPtr`]          [__forward_range__]         [`std::pair<void*,void*> const`]]
    [[`CMapStringToOb`]        [__forward_range__]         [`std::pair<String,CObject*> const`]]
    [[`CMapStringToString`]    [__forward_range__]         [`Range::CPair&`]]
    [[`CMapWordToOb`]          [__forward_range__]         [`std::pair<WORD,CObject*> const`]]
    [[`CMapWordToPtr`]         [__forward_range__]         [`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 below.

Adam Walling has provided the header `<boost/range/mfc_map.hpp>` to add support
for the map adaptor with MFC map types.

[endsect]

[section:atl_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.

[table
    [[Range]                    [Traversal Category]      [`range_reference<Range>::type`]]
    [[`CAtlArray<E,ET>`]        [__random_access_range__] [`E&`]]
    [[`CAutoPtrArray<E>`]       [__random_access_range__] [`E&`]]
    [[`CInterfaceArray<I,pi>`]  [__random_access_range__] [`CComQIPtr<I,pi>&`]]
    [[`CAtlList<E,ET>`]         [__bidirectional_range__] [`E&`]]
    [[`CAutoPtrList<E>`]        [__bidirectional_range__] [`E&`]]
    [[`CHeapPtrList<E,A>`]      [__bidirectional_range__] [`E&`]]
    [[`CInterfaceList<I,pi>`]   [__bidirectional_range__] [`CComQIPtr<I,pi>&`]]
    [[`CAtlMap<K,V,KT,VT>`]     [__forward_range__]       [`Range::CPair&`]]
    [[`CRBTree<K,V,KT,VT>`]     [__bidirectional_range__] [`Range::CPair&`]]
    [[`CRBMap<K,V,KT,VT>`]      [__bidirectional_range__] [`Range::CPair&`]]
    [[`CRBMultiMap<K,V,KT,VT>`] [__bidirectional_range__] [`Range::CPair&`]]
    [[`CSimpleStringT<B,b>`]    [__random_access_range__] [`B&`]]
    [[`CStringT<B,ST>`]         [__random_access_range__] [`B&`]]
    [[`CFixedStringT<S,n>`]     [__random_access_range__] [`range_reference<S>::type`]]
    [[`CComBSTR`]               [__random_access_range__] [`OLECHAR&`]]
    [[`CSimpleArray<T,TE>`]     [__random_access_range__] [`T&`]]
]

Other __boost_range_home__ 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 below.

[endsect]

[section: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`.

``
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.

[table
    [[Range metafunction]                    [Result]]
    [[`range_value<const Range>::type`]      [`range_value<Range>::type`]]
    [[`range_difference<const Range>::type`] [`std::ptrdiff_t`]]
    [[`range_pointer<const Range>::type`]    [`add_pointer<remove_reference<range_reference<const Range>::type>::type>::type`]]
]

[endsect]

[section:references References]

# __boost_range_home__
# __mfc_collections__
# __atl_collections__

[endsect]

[endsect]
Commit	Line	Data
7c673cae FG	1	[/
	2	Copyright 2010 Neil Groves
	3	Distributed under the Boost Software License, Version 1.0.
	4	(See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
	5	/]
	6	[def __mfc_collections__ [@http://msdn.microsoft.com/en-us/library/942860sh.aspx MFC Collection Classes]]
	7	[def __atl_collections__ [@http://msdn.microsoft.com/en-us/library/15e672bd.aspx ATL Collection Classes]]
	8
	9	[section:mfc_atl MFC/ATL (courtesy of Shunsuke Sogame)]
	10
	11	[h4 Introduction]
	12	This implementation was kindly donated by Shunsuke Sogame. This header adapts MFC and ATL containers to the appropriate Range concepts.
	13
	14	[table
	15	[]
	16	[[[*Author:]] [Shunsuke Sogame]]
	17	[[[*Contact:]] [mb2act@yahoo.co.jp]]
	18	[[[*Date:]] [26th of May 2006]]
	19	[[[*Copyright:]] [Shunsuke Sogame 2005-2006. Use, modification and distribution is subject to the Boost Software License, Version 1.0]]
	20	]
	21
	22	[h4 Overview]
	23
	24	Boost.Range MFC/ATL Extension provides Boost.Range support for MFC/ATL collection and string types.
	25
	26	``
	27	CTypedPtrArray<CPtrArray, CList<CString> *> myArray;
	28	...
	29	BOOST_FOREACH (CList<CString> *theList, myArray)
	30	{
	31	BOOST_FOREACH (CString& str, *theList)
	32	{
	33	boost::to_upper(str);
	34	std::sort(boost::begin(str), boost::end(str));
	35	...
	36	}
	37	}
	38	``
	39
	40	[section:requirements Requirements]
	41
	42	* Boost C++ Libraries Version 1.34.0 or later (no compilation required)
	43	* Visual C++ 7.1 or later (for MFC and ATL)
	44
	45	[endsect]
	46
	47	[section:mfc_ranges MFC Ranges]
	48	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.
	49
	50	[table
	51	[[Range] [Traversal Category] [`range_reference<Range>::type`]]
	52	[[`CArray<T,A>`] [__random_access_range__] [`T&`]]
	53	[[`CList<T,A>`] [__bidirectional_range__] [`T&`]]
	54	[[`CMap<K,AK,M,AM>`] [__forward_range__] [`Range::CPair&`]]
	55	[[`CTypedPtrArray<B,T>`] [__random_access_range__] [`T const`]]
	56	[[`CTypedPtrList<B,T>`] [__bidirectional_range__] [`T const`]]
	57	[[`CTypedPtrMap<B,T,V>`] [__forward_range__] [`std::pair<T,V> const`]]
	58	[[`CByteArray`] [__random_access_range__] [`BYTE&`]]
	59	[[`CDWordArray`] [__random_access_range__] [`DWORD&`]]
	60	[[`CObArray`] [__random_access_range__] [`CObject*&`]]
	61	[[`CPtrArray`] [__random_access_range__] [`void*&`]]
	62	[[`CStringArray`] [__random_access_range__] [`CString&`]]
	63	[[`CUIntArray`] [__random_access_range__] [`UINT&`]]
	64	[[`CWordArray`] [__random_access_range__] [`WORD&`]]
65	[[`CObList`] [__bidirectional_range__] [`CObject*&`]]
66	[[`CPtrList`] [__bidirectional_range__] [`void*&`]]
67	[[`CStringList`] [__bidirectional_range__] [`CString&`]]
68	[[`CMapPtrToWord`] [__forward_range__] [`std::pair<void*,WORD> const`]]
69	[[`CMapPtrToPtr`] [__forward_range__] [`std::pair<void,void> const`]]
70	[[`CMapStringToOb`] [__forward_range__] [`std::pair<String,CObject*> const`]]
71	[[`CMapStringToString`] [__forward_range__] [`Range::CPair&`]]
72	[[`CMapWordToOb`] [__forward_range__] [`std::pair<WORD,CObject*> const`]]
73	[[`CMapWordToPtr`] [__forward_range__] [`std::pair<WORD,void*> const`]]
74	]
75
76	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 below.
77
78	Adam Walling has provided the header `<boost/range/mfc_map.hpp>` to add support
79	for the map adaptor with MFC map types.
80
81	[endsect]
82
83	[section:atl_ranges ATL Ranges]
84
85	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.
86
87	[table
88	[[Range] [Traversal Category] [`range_reference<Range>::type`]]
89	[[`CAtlArray<E,ET>`] [__random_access_range__] [`E&`]]
90	[[`CAutoPtrArray<E>`] [__random_access_range__] [`E&`]]
91	[[`CInterfaceArray<I,pi>`] [__random_access_range__] [`CComQIPtr<I,pi>&`]]
92	[[`CAtlList<E,ET>`] [__bidirectional_range__] [`E&`]]
93	[[`CAutoPtrList<E>`] [__bidirectional_range__] [`E&`]]
94	[[`CHeapPtrList<E,A>`] [__bidirectional_range__] [`E&`]]
95	[[`CInterfaceList<I,pi>`] [__bidirectional_range__] [`CComQIPtr<I,pi>&`]]
96	[[`CAtlMap<K,V,KT,VT>`] [__forward_range__] [`Range::CPair&`]]
97	[[`CRBTree<K,V,KT,VT>`] [__bidirectional_range__] [`Range::CPair&`]]
98	[[`CRBMap<K,V,KT,VT>`] [__bidirectional_range__] [`Range::CPair&`]]
99	[[`CRBMultiMap<K,V,KT,VT>`] [__bidirectional_range__] [`Range::CPair&`]]
100	[[`CSimpleStringT<B,b>`] [__random_access_range__] [`B&`]]
101	[[`CStringT<B,ST>`] [__random_access_range__] [`B&`]]
102	[[`CFixedStringT<S,n>`] [__random_access_range__] [`range_reference<S>::type`]]
103	[[`CComBSTR`] [__random_access_range__] [`OLECHAR&`]]
104	[[`CSimpleArray<T,TE>`] [__random_access_range__] [`T&`]]
105	]
106
107	Other __boost_range_home__ 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 below.
108
109	[endsect]
110
111	[section:const_ranges const Ranges]
112
113	`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`.
114
115	``
116	if (Range is CObArray \|\| Range is CObList)
117	return CObject const * &
118	else if (Range is CPtrArray \|\| Range is CPtrList)
119	return void const * &
120	else if (there is a type X such that X& is the same as Ref)
121	return X const &
122	else if (there is a type X such that X* const is the same as Ref)
123	return X const * const
124	else
125	return Ref
126	``
127
128
129	Other Boost.Range metafunctions are defined by the following.
130
131	[table
132	[[Range metafunction] [Result]]
133	[[`range_value<const Range>::type`] [`range_value<Range>::type`]]
134	[[`range_difference<const Range>::type`] [`std::ptrdiff_t`]]
135	[[`range_pointer<const Range>::type`] [`add_pointer<remove_reference<range_reference<const Range>::type>::type>::type`]]
136	]
137
138	[endsect]
139
140	[section:references References]
141
142	# __boost_range_home__
143	# __mfc_collections__
144	# __atl_collections__
145
146	[endsect]
147
148	[endsect]