2 Copyright (c) 2008-2010 Joachim Faulhaber
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)
13 [table Overview over Icl Examples
14 [[level] [example] [classes] [features]]
15 [[intro][[link boost_icl.examples.party Party]]
16 [__itv_map__][Generates an attendance history of a party
17 by inserting into an __itv_map__.
19 ['*aggregate on overlap*].]]
20 [[basic] [[link boost_icl.examples.interval Interval]]
21 [__dc_itv__, __ct_itv__ ] [Intervals for discrete and continuous instance types.
22 Closed and open interval borders.]]
23 [[basic] [[link boost_icl.examples.dynamic_interval Dynamic intervals]]
24 [__dc_itv__, __ct_itv__, __itv__ ] [Intervals with dynamic interval bounds as library default.]]
25 [[basic] [[link boost_icl.examples.static_interval Static intervals]]
26 [__ro_itv__, __itv__ ] [Intervals with static interval bounds and changing the library default.]]
27 [[basic] [[link boost_icl.examples.interval_container Interval container]]
28 [__itv_set__,\n__sep_itv_set__,\n__spl_itv_set__,\n__spl_itv_map__,\n__itv_map__]
29 [Basic characteristics of interval containers.]]
30 [[basic] [[link boost_icl.examples.overlap_counter Overlap counter]]
31 [__itv_map__][The most simple application of an interval map:
32 Counting the overlaps of added intervals.]]
33 [[advanced][[link boost_icl.examples.partys_height_average Party's height average]]
34 [__itv_map__][Using /aggregate on overlap/ a history of height averages of party guests is computed.
35 Associated values are user defined class objects, that implement
36 an appropriate `operator +=` for the aggregation.]]
37 [[advanced][[link boost_icl.examples.partys_tallest_guests Party's tallest guests]]
38 [__itv_map__,\n__spl_itv_map__]
39 [Using /aggregate on overlap/ the heights of the party's tallest guests are computed.
40 Associated values are aggregated via a maximum functor, that can
41 be chosen as template parameter of an interval_map class template.]]
42 [[advanced][[link boost_icl.examples.time_grids Time grids for months and weeks]]
44 [Shows how the ['*border preserving*]
45 __spl_itv_set__ can be used to create time partitions where different
46 periodic time intervals overlay each other.]]
47 [[advanced][[link boost_icl.examples.man_power Man power]]
48 [__itv_set__,\n__itv_map__]
49 [Set style operations on __itv_sets__ and __itv_maps__ like union, difference
50 and intersection can be used to obtain calculations in a flexible way. Example
51 [*man_power] demonstrates such operations in the process of calculating the
52 available man-power of a company in a given time interval.]]
53 [[advanced][[link boost_icl.examples.user_groups User groups]][__itv_map__]
54 [Example [*user_groups] shows how interval_maps can be unified or
55 intersected to calculate desired information.]]
57 [[and std] [[link boost_icl.examples.std_copy Std copy]]
58 [__itv_map__][Fill interval containers using `std::copy`.]]
59 [[and std] [[link boost_icl.examples.std_transform Std transform]]
60 [__itv_map__,\n__sep_itv_set__][Fill interval containers from user defined objects using `std::transform`.]]
62 [[customize] [[link boost_icl.examples.custom_interval Custom interval]]
63 [__itv_tr__][Use interval containers with your own interval class types.]]
70 [import ../example/boost_party_/boost_party.cpp]
72 Example *party* demonstrates the possibilities of an interval map
73 (__itv_map__ or __spl_itv_map__).
74 An __itv_map__ maps intervals to a given content. In this case the
75 content is a set of party guests represented by their name strings.
77 As time goes by, groups of people join the party and leave later in the evening.
78 So we add a time interval and a name set to the __itv_map__ for the attendance
79 of each group of people, that come together and leave together.
80 On every overlap of intervals, the corresponding name sets are accumulated. At
81 the points of overlap the intervals are split. The accumulation of content
82 is done via an operator += that has to be implemented
83 for the content parameter of the __itv_map__.
84 Finally the interval_map contains the history of attendance and all points in
85 time, where the group of party guests changed.
87 Party demonstrates a principle that we call
88 ['*aggregate on overlap*]:
89 On insertion a value associated to the interval is aggregated with those
90 values in the interval_map that overlap with the inserted value.
91 There are two behavioral aspects to ['*aggregate on overlap*]: a ['*decompositional
92 behavior*] and an ['*accumulative behavior*].
94 * The ['*decompositional behavior*] splits up intervals on the /time/ /dimension/ of the
95 interval_map so that the intervals are split whenever associated values
98 * The ['*accumulative behavior*] accumulates associated values on every overlap of
99 an insertion for the associated values.
101 The aggregation function is += by default. Different aggregations can
105 [example_boost_party]
109 We are introducing __itv_maps__ using an
110 ['interval map ['*of sets of strings*]],
111 because of it's didactic advantages. The party example is
112 used to give an immediate access to the basic ideas of
113 interval maps and /aggregate on overlap/.
114 For real world applications, an interval_map of sets is
115 not necessarily recommended.
116 It has the same efficiency problems as
117 a `std::map` of `std::sets`.
118 There is a big realm though of using
119 interval_maps with numerical and other
120 efficient data types for the associated values.
128 Example *interval* shows some basic functionality of __itvs__.
130 * Different instances of __itvs__ for integral ([^int, Time]) and
131 continuous types ([^double, std::string]) are used.
133 * The examples uses open and closed intervals bounds.
135 * Some borderline functions calls on open interval borders are tested e.g.:
136 `interval<double>::rightopen(1/sqrt(2.0), sqrt(2.0)).contains(sqrt(2.0));`
138 [import ../example/interval_/interval.cpp]
142 [section Dynamic interval]
143 [import ../example/dynamic_interval_/dynamic_interval.cpp]
144 [example_dynamic_interval]
147 [section Static interval]
148 [import ../example/static_interval_/static_interval.cpp]
149 [example_static_interval]
153 [section Interval container]
155 Example [*interval container] demonstrates the characteristic behaviors
156 of different interval containers that are also summarized
157 in the introductory [link boost_icl.introduction.interval_combining_styles Interval Combining Styles].
159 [import ../example/interval_container_/interval_container.cpp]
160 [example_interval_container]
164 [section Overlap counter]
166 Example [*overlap counter] provides the simplest application
167 of an interval_map that maps intervals to integers.
168 An interval_map<int,int> serves as an overlap counter
169 if we only add interval value pairs that carry 1 as
172 Doing so, the associated values that are accumulated in
173 the interval_map are just the number of overlaps of all added
176 [import ../example/overlap_counter_/overlap_counter.cpp]
177 [example_overlap_counter]
182 [section:partys_height_average Party's height average]
184 In the example `partys_height_average.cpp` we compute yet another aggregation:
185 The average height of guests. This is done by defining a `class counted_sum`
186 that sums up heights and counts the number of guests
187 via an `operator +=`.
189 Based on the `operator +=` we can aggregate counted sums on addition
190 of interval value pairs into an interval_map.
192 [import ../example/partys_height_average_/partys_height_average.cpp]
193 [example_partys_height_average]
195 Required for `class counted_sum` is a default constructor
197 an `operator ==` to test equality.
198 To enable additive aggregation on overlap also
199 an `operator +=` is needed.
201 Note that no `operator -=` for a subtraction of `counted_sum` values
202 is defined. So you can only add to the
203 `interval_map<ptime, counted_sum>`
204 but not subtract from it.
206 In many real world applications only addition is needed and user
207 defined classes will work fine, if they only implement
208 `operator +=`. Only if any of the `operator`s `-=` or `-`
209 is called on the interval_map, the user defined class has to
210 implement it's own `operator -=` to provide the subtractive
211 aggregation on overlap.
216 [section:partys_tallest_guests Party's tallest guests]
218 Defining `operator +=` (and `-=`) is probably the most important
219 method to implement arbitrary kinds of user defined aggregations.
220 An alternative way to choose a desired aggregation is to
221 instantiate an interval_map class template with an
222 appropriate ['*aggregation functor*]. For the most common
223 kinds of aggregation the [*icl]
224 provides such functors as shown in the example.
226 Example `partys_tallest_guests.cpp` also demonstrates
227 the difference between an __itv_map__
228 that joins intervals for equal associated values and a
229 __spl_itv_map__ that preserves all borders of inserted
232 [import ../example/partys_tallest_guests_/partys_tallest_guests.cpp]
233 [example_partys_tallest_guests]
237 [section:time_grids Time grids for months and weeks]
239 A __spl_itv_set__ preserves all interval borders on insertion
240 and intersection operations. So given a __spl_itv_set__ and an addition of an interval
245 then the intervals are split at their borders
247 x == {[1,2)[2,3)[3,4)}
249 Using this property we can intersect __spl_itv_maps__ in
250 order to iterate over intervals accounting for all occurring
251 changes of interval borders.
253 In this example we provide an intersection of two __spl_itv_sets__
254 representing a month and week time grid.
256 [import ../example/month_and_week_grid_/month_and_week_grid.cpp]
257 [example_month_and_week_grid]
262 __Itv_sets__ and __itv_maps__ can be filled and manipulated using
263 set style operations such as union `+=`, difference `-=` and
266 In this example [*man power] a number of those operations are
267 demonstrated in the process of calculation the available working
268 times (man-power) of a company's employees accounting for weekends,
269 holidays, sickness times and vacations.
271 [import ../example/man_power_/man_power.cpp]
275 [section User groups]
277 Example [*user groups] shows the availability of set operations
280 In the example there is a user group `med_users` of a hospital staff
281 that has the authorisation to handle medical data of patients.
282 User group `admin_users` has access to administrative data like
283 health insurance and financial data.
285 The membership for each user in one of the user groups has a time
286 interval of validity. The group membership begins and ends.
288 * Using a union operation `+` we can have an overview over the unified
289 user groups and the membership dates of employees.
291 * Computing an intersection `&` shows who is member of both med_users
292 and admin_users at what times.
294 [import ../example/user_groups_/user_groups.cpp]
295 [example_user_groups]
301 The standard algorithm
302 [@http://www.cplusplus.com/reference/algorithm/copy/ `std::copy`]
303 can be used to fill interval containers
304 from standard containers of intervals or
305 interval value pairs (segments). Because intervals
306 do not represent ['*elements*] but ['*sets*], that
307 can be empty or contain more than one element,
308 the usage of `std::copy` differs from what we
309 are familiar with using ['containers of elements].
311 * Use `icl::inserter` from `#include <boost/icl/iterator.hpp>`
312 instead of `std::inserter` to call insertions on the target
315 * As shown in the examples above and below this point, most of
316 the time we will not be interested to `insert` segments
317 into __itv_maps__ but to __biLadd__
318 them, in order to generate the desired aggregation results.
319 You can use `std::copy` with an `icl::adder` instead of an
320 `icl::inserter` to achieve this.
322 [import ../example/std_copy_/std_copy.cpp]
325 [endsect][/ Std copy]
328 [section Std transform]
330 Instead of writing loops, the standard algorithm
331 [@http://www.cplusplus.com/reference/algorithm/transform/ `std::transform`]
332 can be used to fill interval containers
333 from std containers of user defined objects.
334 We need a function, that
335 maps the ['user defined object] into the
336 ['segement type] of an interval map or the
337 ['interval type] of an interval set.
338 Based on that we can use `std::transform`
339 with an `icl::inserter` or `icl::adder`
340 to transform the user objects into interval
343 [import ../example/std_transform_/std_transform.cpp]
344 [example_std_transform]
346 To get clear about the different behaviors of interval containers
347 in the example, you may want to refer to the section about
348 [link boost_icl.introduction.interval_combining_styles interval combining styles]
349 that uses the same data.
352 Instead of `icl::inserter` we could also use an `std::inserter`
353 with algorithms `std::copy` and `std::transform`.
354 This is ['*depreciated*], because `std::inserter` is designed for
355 containers of elements, where ['*exacty one*] element is inserted
356 via `std::inserter` if it is not already in the container.
357 In contrast to that, an interval or segemnt can represent zero, one,
358 or many elements of an interval container.
360 You can use `std::inserter` *only*, if you actively take care of
363 # None of the intervals or segements of the source containers
366 # A segment never carries a neutral element when your target
367 interval map absorbs identities.
369 Violating those preconditions leads to ['*undefined behavior*].
372 [endsect][/ std::transform]
375 [section Custom interval]
377 Example *custom interval* demonstrates how to use interval
378 containers with an own interval class type.
380 [import ../example/custom_interval_/custom_interval.cpp]
381 [example_custom_interval]
382 [endsect][/ Custom interval]
386 [endsect][/ examples]