[ceph.git] / ceph / src / boost / libs / icl / doc / functions_element_iteration.qbk

[/
    Copyright (c) 2008-2009 Joachim Faulhaber

    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)
]


[/ //= Element iteration ===================================================================]
[section Element iteration]

This section refers to ['*element iteration*] over ['*interval containers*].
Element iterators are available as associated types on interval sets and interval maps.

[table
[[Variant]      [Associated element iterator type for interval container `T`]]
[[forward]      [`T::element_iterator`]                                    ]
[[const forward][`T::element_const_iterator`]                              ]
[[reverse]      [`T::element_reverse_iterator`]                            ]
[[const reverse][`T::element_const_reverse_iterator`]                      ]
]

There are also associated iterators types 
`T::iterator`, `T::const_iterator`, 
`T::reverse_iterator` and `T::reverse_const_iterator`
on interval containers.
These are ['*segment iterators*]. Segment iterators are 
"first citizen iterators". [/ NOTE Identical to interface.qbk from here]
Iteration over segments is fast, compared to an iteration over elements,
particularly if intervals are large. 
But if we want to view our interval containers as containers
of elements that are usable with std::algoritms, we need to
iterate over elements. 

Iteration over elements . . .

* is possible only for integral or discrete `domain_types`
* can be very ['*slow*] if the intervals are very large.
* and is therefore ['*depreciated*]

On the other hand, sometimes iteration over interval containers
on the element level might be desired, if you have some 
interface that works for `std::SortedAssociativeContainers` of 
elements and you need to quickly use it with an interval container.
Accepting the poorer performance might be less bothersome at times
than adjusting your whole interface for segment iteration.

[caution So we advice you to choose element iteration over
interval containers ['*judiciously*]. Do not use element iteration
['*by default or habitual*]. Always try to achieve results using
member functions, global functions or operators 
(preferably inplace versions)
or iteration over segments first.]


[table
[[['*Synopsis Complexities*]]   [__ch_itv_sets__][__ch_itv_maps__]]
[[`J elements_begin(T&)`]               [__O1__]    [__O1__]     ]
[[`J elements_end(T&)`]                 [__O1__]    [__O1__]     ]
[[`J elements_rbegin(T&)`]              [__O1__]    [__O1__]     ]
[[`J elements_rend(T&)`]                [__O1__]    [__O1__]     ]
]

[table
[[['*Element iteration*]]                                      [Description]     ]
[[``      element_iterator elements_begin(T&)
element_const_iterator elements_begin(const T&)``]          [Returns an element iterator to the first element of the container.]                        ]
[[``      element_iterator elements_end(T&)
element_const_iterator elements_end(const T&)``]            [Returns an element iterator to a position `elements_end(c)` after the last element of the container.]]
[[``      element_reverse_iterator elements_rbegin(T&)
element_const_reverse_iterator elements_rbegin(const T&)``] [Returns a reverse element iterator to the last element of the container.]                  ]
[[``      element_reverse_iterator elements_rend(T&)
element_const_reverse_iterator elements_rend(const T&)``]   [Returns a reverse element iterator to a position `elements_rend(c)` before the first element of the container.]]
]

['*Example*]

``
interval_set<int> inter_set;
inter_set.add(interval<int>::right_open(0,3))
         .add(interval<int>::right_open(7,9));

for(interval_set<int>::element_const_iterator creeper = elements_begin(inter_set); 
    creeper != elements_end(inter_set); ++creeper)
    cout << *creeper << " ";
cout << endl;
//Program output: 0 1 2 7 8

for(interval_set<int>::element_reverse_iterator repeerc = elements_rbegin(inter_set); 
    repeerc != elements_rend(inter_set); ++repeerc)
    cout << *repeerc << " ";
cout << endl;
//Program output: 8 7 2 1 0
``

['*See also . . .*]
[table
[]
[[[link boost_icl.function_reference.iterator_related ['*Segment iteration*]]   ]]
]

['*Back to section . . .*]
[table
[]
[[[link function_synopsis_table ['*Function Synopsis*]]]]
[[[link boost_icl.interface ['*Interface*]]                          ]]
]

[endsect][/ Element iteration]
Commit	Line	Data
7c673cae FG	1	[/
	2	Copyright (c) 2008-2009 Joachim Faulhaber
	3
	4	Distributed under the Boost Software License, Version 1.0.
	5	(See accompanying file LICENSE_1_0.txt or copy at
	6	http://www.boost.org/LICENSE_1_0.txt)
	7	]
	8
	9
	10	[/ //= Element iteration ===================================================================]
	11	[section Element iteration]
	12
	13	This section refers to ['element iteration] over ['interval containers].
	14	Element iterators are available as associated types on interval sets and interval maps.
	15
	16	[table
	17	[[Variant] [Associated element iterator type for interval container `T`]]
	18	[[forward] [`T::element_iterator`] ]
	19	[[const forward][`T::element_const_iterator`] ]
	20	[[reverse] [`T::element_reverse_iterator`] ]
	21	[[const reverse][`T::element_const_reverse_iterator`] ]
	22	]
	23
	24	There are also associated iterators types
	25	`T::iterator`, `T::const_iterator`,
	26	`T::reverse_iterator` and `T::reverse_const_iterator`
	27	on interval containers.
	28	These are ['segment iterators]. Segment iterators are
	29	"first citizen iterators". [/ NOTE Identical to interface.qbk from here]
	30	Iteration over segments is fast, compared to an iteration over elements,
	31	particularly if intervals are large.
	32	But if we want to view our interval containers as containers
	33	of elements that are usable with std::algoritms, we need to
	34	iterate over elements.
	35
	36	Iteration over elements . . .
	37
	38	* is possible only for integral or discrete `domain_types`
	39	* can be very ['slow] if the intervals are very large.
	40	* and is therefore ['depreciated]
	41
	42	On the other hand, sometimes iteration over interval containers
	43	on the element level might be desired, if you have some
	44	interface that works for `std::SortedAssociativeContainers` of
	45	elements and you need to quickly use it with an interval container.
	46	Accepting the poorer performance might be less bothersome at times
	47	than adjusting your whole interface for segment iteration.
	48
	49	[caution So we advice you to choose element iteration over
	50	interval containers ['judiciously]. Do not use element iteration
	51	['by default or habitual]. Always try to achieve results using
	52	member functions, global functions or operators
	53	(preferably inplace versions)
	54	or iteration over segments first.]
	55
	56
	57	[table
	58	[[['Synopsis Complexities]] [__ch_itv_sets__][__ch_itv_maps__]]
	59	[[`J elements_begin(T&)`] [__O1__] [__O1__] ]
	60	[[`J elements_end(T&)`] [__O1__] [__O1__] ]
	61	[[`J elements_rbegin(T&)`] [__O1__] [__O1__] ]
	62	[[`J elements_rend(T&)`] [__O1__] [__O1__] ]
	63	]
	64
65	[table
66	[[['Element iteration]] [Description] ]
67	[[`` element_iterator elements_begin(T&)
68	element_const_iterator elements_begin(const T&)``] [Returns an element iterator to the first element of the container.] ]
69	[[`` element_iterator elements_end(T&)
70	element_const_iterator elements_end(const T&)``] [Returns an element iterator to a position `elements_end(c)` after the last element of the container.]]
71	[[`` element_reverse_iterator elements_rbegin(T&)
72	element_const_reverse_iterator elements_rbegin(const T&)``] [Returns a reverse element iterator to the last element of the container.] ]
73	[[`` element_reverse_iterator elements_rend(T&)
74	element_const_reverse_iterator elements_rend(const T&)``] [Returns a reverse element iterator to a position `elements_rend(c)` before the first element of the container.]]
75	]
76
77	['Example]
78
79	``
80	interval_set<int> inter_set;
81	inter_set.add(interval<int>::right_open(0,3))
82	.add(interval<int>::right_open(7,9));
83
84	for(interval_set<int>::element_const_iterator creeper = elements_begin(inter_set);
85	creeper != elements_end(inter_set); ++creeper)
86	cout << *creeper << " ";
87	cout << endl;
88	//Program output: 0 1 2 7 8
89
90	for(interval_set<int>::element_reverse_iterator repeerc = elements_rbegin(inter_set);
91	repeerc != elements_rend(inter_set); ++repeerc)
92	cout << *repeerc << " ";
93	cout << endl;
94	//Program output: 8 7 2 1 0
95	``
96
97	['See also . . .]
98	[table
99	[]
100	[[[link boost_icl.function_reference.iterator_related ['Segment iteration]] ]]
101	]
102
103	['Back to section . . .]
104	[table
105	[]
106	[[[link function_synopsis_table ['Function Synopsis]]]]
107	[[[link boost_icl.interface ['Interface]] ]]
108	]
109
110	[endsect][/ Element iteration]
111
112