3 <meta http-equiv=
"Content-Type" content=
"text/html; charset=US-ASCII">
4 <title>Map Traits
</title>
5 <link rel=
"stylesheet" href=
"../../../../../../doc/src/boostbook.css" type=
"text/css">
6 <meta name=
"generator" content=
"DocBook XSL Stylesheets V1.74.0">
7 <link rel=
"home" href=
"../../index.html" title=
"Chapter 1. Boost.Icl">
8 <link rel=
"up" href=
"../concepts.html" title=
"Concepts">
9 <link rel=
"prev" href=
"aggrovering.html" title=
"Addability, Subtractability and Aggregate on Overlap">
10 <link rel=
"next" href=
"../semantics.html" title=
"Semantics">
12 <body bgcolor=
"white" text=
"black" link=
"#0000FF" vlink=
"#840084" alink=
"#0000FF">
13 <table cellpadding=
"2" width=
"100%"><tr>
14 <td valign=
"top"><img alt=
"Boost C++ Libraries" width=
"277" height=
"86" src=
"../../../../../../boost.png"></td>
15 <td align=
"center"><a href=
"../../../../../../index.html">Home
</a></td>
16 <td align=
"center"><a href=
"../../../../../libraries.htm">Libraries
</a></td>
17 <td align=
"center"><a href=
"http://www.boost.org/users/people.html">People
</a></td>
18 <td align=
"center"><a href=
"http://www.boost.org/users/faq.html">FAQ
</a></td>
19 <td align=
"center"><a href=
"../../../../../../more/index.htm">More
</a></td>
22 <div class=
"spirit-nav">
23 <a accesskey=
"p" href=
"aggrovering.html"><img src=
"../../../../../../doc/src/images/prev.png" alt=
"Prev"></a><a accesskey=
"u" href=
"../concepts.html"><img src=
"../../../../../../doc/src/images/up.png" alt=
"Up"></a><a accesskey=
"h" href=
"../../index.html"><img src=
"../../../../../../doc/src/images/home.png" alt=
"Home"></a><a accesskey=
"n" href=
"../semantics.html"><img src=
"../../../../../../doc/src/images/next.png" alt=
"Next"></a>
25 <div class=
"section boost_icl_concepts_map_traits" lang=
"en">
26 <div class=
"titlepage"><div><div><h3 class=
"title">
27 <a name=
"boost_icl.concepts.map_traits"></a><a class=
"link" href=
"map_traits.html" title=
"Map Traits">Map Traits
</a>
28 </h3></div></div></div>
30 Icl maps differ in their behavior dependent on how they handle
<a href=
"http://en.wikipedia.org/wiki/Identity_element" target=
"_top"><span class=
"emphasis"><em><span class=
"bold"><strong>identity elements
</strong></span></em></span></a> of the associated
31 type
<code class=
"computeroutput"><span class=
"identifier">CodomainT
</span></code>.
33 <a name=
"boost_icl.concepts.map_traits.remarks_on_identity_elements"></a><h5>
34 <a name=
"id1079765"></a>
35 <a class=
"link" href=
"map_traits.html#boost_icl.concepts.map_traits.remarks_on_identity_elements">Remarks
36 on Identity Elements
</a>
39 In the pseudo code snippets below
<code class=
"computeroutput"><span class=
"number">0</span></code>
40 will be used to denote
<a href=
"http://en.wikipedia.org/wiki/Identity_element" target=
"_top"><code class=
"computeroutput"><span class=
"identifier">identity
</span> <span class=
"identifier">elements
</span></code></a>,
41 which can be different objects like
<code class=
"computeroutput"><span class=
"keyword">const
</span>
42 <span class=
"keyword">double
</span> <span class=
"number">0.0</span></code>,
43 empty sets, empty strings, null-vectors etc. dependent of the instance type
44 for parameter
<code class=
"computeroutput"><span class=
"identifier">CodomainT
</span></code>.
45 The existence of an
<span class=
"emphasis"><em><span class=
"bold"><strong>identity element
</strong></span></em></span>
46 wrt. an
<code class=
"computeroutput"><span class=
"keyword">operator
</span><span class=
"special">+=
</span></code>
47 is a requirement for template type
<code class=
"computeroutput"><span class=
"identifier">CodomainT
</span></code>.
49 <div class=
"informaltable"><table class=
"table">
76 <code class=
"computeroutput"><span class=
"keyword">int
</span></code>
86 <code class=
"computeroutput"><span class=
"number">0</span></code>
93 <code class=
"computeroutput"><span class=
"identifier">string
</span></code>
103 <code class=
"computeroutput"><span class=
"string">""</span></code>
110 <code class=
"computeroutput"><span class=
"identifier">set
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">></span></code>
120 <code class=
"computeroutput"><span class=
"special">{}
</span></code>
127 In these cases the
<code class=
"computeroutput"><span class=
"identifier">identity
</span> <span class=
"identifier">element
</span></code> value is delivered by the default
128 constructor of the maps
<code class=
"computeroutput"><span class=
"identifier">CodomainT
</span></code>
129 type. But there are well known exceptions like e.g. numeric multiplication:
131 <div class=
"informaltable"><table class=
"table">
157 <code class=
"computeroutput"><span class=
"keyword">int
</span></code>
167 <code class=
"computeroutput"><span class=
"number">1</span></code>
173 Therefore icl functors, that serve as
<code class=
"computeroutput"><span class=
"identifier">Combiner
</span></code>
174 parameters of icl Maps implement a static function
<code class=
"computeroutput"><span class=
"identifier">identity_element
</span><span class=
"special">()
</span></code> to make sure that the correct
<code class=
"computeroutput"><span class=
"identifier">identity_element
</span><span class=
"special">()
</span></code>
175 is used in the implementation of
<span class=
"emphasis"><em>aggregate on overlap
</em></span>.
178 <pre class=
"programlisting"><span class=
"identifier">inplace_times
</span><span class=
"special"><</span><span class=
"keyword">int
</span><span class=
"special">>::
</span><span class=
"identifier">identity_element
</span><span class=
"special">()
</span> <span class=
"special">==
</span> <span class=
"number">1</span>
179 <span class=
"comment">// or more general
180 </span><span class=
"identifier">inplace_times
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>::
</span><span class=
"identifier">identity_element
</span><span class=
"special">()
</span> <span class=
"special">==
</span> <span class=
"identifier">unit_element
</span><span class=
"special"><</span><span class=
"identifier">T
</span><span class=
"special">>::
</span><span class=
"identifier">value
</span><span class=
"special">()
</span>
184 <a name=
"boost_icl.concepts.map_traits.definedness_and_storage_of_identity_elements"></a><h5>
185 <a name=
"id1081881"></a>
186 <a class=
"link" href=
"map_traits.html#boost_icl.concepts.map_traits.definedness_and_storage_of_identity_elements">Definedness
187 and Storage of Identity Elements
</a>
190 There are two
<span class=
"emphasis"><em>properties
</em></span> or
<span class=
"emphasis"><em>traits
</em></span>
191 of icl maps that can be chosen by a template parameter
<code class=
"computeroutput"><span class=
"identifier">Traits
</span></code>.
192 The
<span class=
"emphasis"><em><span class=
"bold"><strong>first trait
</strong></span></em></span> relates
193 to the
<span class=
"emphasis"><em><span class=
"bold"><strong>definedness
</strong></span></em></span>
194 of the map. Icl maps can be
<span class=
"bold"><strong>partial
</strong></span> or
195 <span class=
"bold"><strong>total
</strong></span> on the set of values given by domain
196 type
<code class=
"computeroutput"><span class=
"identifier">DomainT
</span></code>.
198 <div class=
"itemizedlist"><ul type=
"disc">
200 A
<span class=
"emphasis"><em><span class=
"bold"><strong>partial
</strong></span></em></span> map is
201 only defined on those key elements that have been inserted into the Map.
202 This is usually expected and so
<span class=
"emphasis"><em><span class=
"bold"><strong>partial
203 definedness
</strong></span></em></span> is the default.
206 Alternatively an icl Map can be
<span class=
"emphasis"><em><span class=
"bold"><strong>total
</strong></span></em></span>.
207 It is then considered to contain a
<span class=
"emphasis"><em><span class=
"bold"><strong>neutral
208 value
</strong></span></em></span> for all key values that are not stored in the
213 The
<span class=
"emphasis"><em><span class=
"bold"><strong>second trait
</strong></span></em></span> is
214 related to the representation of
<code class=
"computeroutput"><span class=
"identifier">identity
</span>
215 <span class=
"identifier">elements
</span></code> in the map. An icl map
216 can be a
<span class=
"emphasis"><em><span class=
"bold"><strong>identity absorber
</strong></span></em></span>
217 or a
<span class=
"emphasis"><em><span class=
"bold"><strong>identity enricher
</strong></span></em></span>.
219 <div class=
"itemizedlist"><ul type=
"disc">
221 A
<span class=
"emphasis"><em><span class=
"bold"><strong>identity absorber
</strong></span></em></span>
222 never stores value pairs
<code class=
"computeroutput"><span class=
"special">(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">0</span><span class=
"special">)
</span></code> that carry identity elements.
225 A
<span class=
"emphasis"><em><span class=
"bold"><strong>identity enricher
</strong></span></em></span>
226 stores value pairs
<code class=
"computeroutput"><span class=
"special">(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">0</span><span class=
"special">)
</span></code>.
230 For the template parameter
<code class=
"computeroutput"><span class=
"identifier">Traits
</span></code>
231 of icl Maps we have the following four values.
233 <div class=
"informaltable"><table class=
"table">
264 partial_absorber
<span class=
"emphasis"><em>(default)
</em></span>
292 <a name=
"boost_icl.concepts.map_traits.map_traits_motivated"></a><h5>
293 <a name=
"id1082177"></a>
294 <a class=
"link" href=
"map_traits.html#boost_icl.concepts.map_traits.map_traits_motivated">Map Traits
298 Map traits are a late extension to the
<span class=
"bold"><strong>icl
</strong></span>.
299 Interval maps have been used for a couple of years in a variety of applications
300 at Cortex Software GmbH with an implementation that resembled the default
301 trait. Only the deeper analysis of the icl's
<span class=
"emphasis"><em><span class=
"bold"><strong>aggregating
302 Map's concept
</strong></span></em></span> in the course of preparation of the library
303 for boost led to the introduction of map Traits.
305 <a name=
"boost_icl.concepts.map_traits.add_subtract_antinomy_in_aggregating_maps"></a><h6>
306 <a name=
"id1082204"></a>
307 <a class=
"link" href=
"map_traits.html#boost_icl.concepts.map_traits.add_subtract_antinomy_in_aggregating_maps">Add-Subtract
308 Antinomy in Aggregating Maps
</a>
311 Constitutional for the absorber/enricher propery is a little antinomy.
314 We can insert value pairs to the map by
<span class=
"emphasis"><em><span class=
"bold"><strong>adding
</strong></span></em></span>
315 them to the map via operations
<code class=
"computeroutput"><span class=
"identifier">add
</span><span class=
"special">,
</span> <span class=
"special">+=
</span></code> or
<code class=
"computeroutput"><span class=
"special">+
</span></code>:
317 <pre class=
"programlisting"><span class=
"special">{}
</span> <span class=
"special">+
</span> <span class=
"special">{(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">1</span><span class=
"special">)}
</span> <span class=
"special">==
</span> <span class=
"special">{(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">1</span><span class=
"special">)}
</span> <span class=
"comment">// addition
</span></pre>
321 Further addition on common keys triggers aggregation:
323 <pre class=
"programlisting"><span class=
"special">{(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">1</span><span class=
"special">)}
</span> <span class=
"special">+
</span> <span class=
"special">{(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">1</span><span class=
"special">)}
</span> <span class=
"special">==
</span> <span class=
"special">{(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">2</span><span class=
"special">)}
</span> <span class=
"comment">// aggregation for common key k
</span></pre>
327 A subtraction of existing pairs
329 <pre class=
"programlisting"><span class=
"special">{(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">2</span><span class=
"special">)}
</span> <span class=
"special">-
</span> <span class=
"special">{(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">2</span><span class=
"special">)}
</span> <span class=
"special">==
</span> <span class=
"special">{(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">0</span><span class=
"special">)}
</span> <span class=
"comment">// aggregation for common key k
</span></pre>
331 yields value pairs that are associated with
0-values or
<code class=
"computeroutput"><span class=
"identifier">identity
</span>
332 <span class=
"identifier">elements
</span></code>.
335 So once a value pair is created for a key
<code class=
"computeroutput"><span class=
"identifier">k
</span></code>
336 it can not be removed from the map via subtraction (
<code class=
"computeroutput"><span class=
"identifier">subtract
</span><span class=
"special">,
</span> <span class=
"special">-=
</span></code> or
<code class=
"computeroutput"><span class=
"special">-
</span></code>).
339 The very basic fact on sets, that we can remove what we have previously added
342 <pre class=
"programlisting"><span class=
"identifier">x
</span> <span class=
"special">-
</span> <span class=
"identifier">x
</span> <span class=
"special">=
</span> <span class=
"special">{}
</span></pre>
347 This is the motivation for the
<span class=
"emphasis"><em><span class=
"bold"><strong>identity absorber
</strong></span></em></span>
348 Trait. A identity absorber map handles value pairs that carry identity elements
349 as
<span class=
"emphasis"><em><span class=
"bold"><strong>non-existent
</strong></span></em></span>, which
352 <pre class=
"programlisting"><span class=
"identifier">x
</span> <span class=
"special">-
</span> <span class=
"identifier">x
</span> <span class=
"special">=
</span> <span class=
"special">{}
</span></pre>
356 Yet this introduces a new problem: With such a
<span class=
"emphasis"><em>identity absorber
</em></span>
357 we are
<span class=
"emphasis"><em>by definition
</em></span> unable to store a value
<code class=
"computeroutput"><span class=
"special">(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">0</span><span class=
"special">)
</span></code> in the map.
358 This may be unfavorable because it is not inline with the behavior of stl::maps
359 and this is not necessarily expected by clients of the library.
362 The solution to the problem is the introduction of the identity enricher
363 Trait, so the user can choose a map variant according to her needs.
365 <a name=
"boost_icl.concepts.map_traits.partial_and_total_maps"></a><h6>
366 <a name=
"id1082625"></a>
367 <a class=
"link" href=
"map_traits.html#boost_icl.concepts.map_traits.partial_and_total_maps">Partial
371 The idea of a identity absorbing map is, that an
<span class=
"emphasis"><em><span class=
"bold"><strong>associated
372 identity element
</strong></span></em></span> value of a pair
<code class=
"computeroutput"><span class=
"special">(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">0</span><span class=
"special">)
</span></code> <span class=
"emphasis"><em><span class=
"bold"><strong>codes non-existence
</strong></span></em></span>
373 for it's key
<code class=
"computeroutput"><span class=
"identifier">k
</span></code>. So the pair
374 <code class=
"computeroutput"><span class=
"special">(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">0</span><span class=
"special">)
</span></code>
375 immediately tunnels from a map where it may emerge into the realm of non
378 <pre class=
"programlisting"><span class=
"special">{(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">0</span><span class=
"special">)}
</span> <span class=
"special">==
</span> <span class=
"special">{}
</span></pre>
382 If identity elements do not code
<span class=
"emphasis"><em><span class=
"bold"><strong>non-existence
</strong></span></em></span>
383 but
<span class=
"emphasis"><em><span class=
"bold"><strong>existence with null quantification
</strong></span></em></span>,
384 we can also think of a map that has an associated identity element
<span class=
"emphasis"><em><span class=
"bold"><strong>for every
</strong></span></em></span> key
<code class=
"computeroutput"><span class=
"identifier">k
</span></code>
385 that has no associated value different from
0. So in contrast to modelling
386 <span class=
"bold"><strong>all
</strong></span> neutral value pairs
<code class=
"computeroutput"><span class=
"special">(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">0</span><span class=
"special">)
</span></code> as being
<span class=
"emphasis"><em><span class=
"bold"><strong>non-existent
</strong></span></em></span>
387 we can model
<span class=
"bold"><strong>all
</strong></span> neutral value pairs
<code class=
"computeroutput"><span class=
"special">(
</span><span class=
"identifier">k
</span><span class=
"special">,
</span><span class=
"number">0</span><span class=
"special">)
</span></code> as being
388 <span class=
"emphasis"><em><span class=
"bold"><strong>implicitly existent
</strong></span></em></span>.
391 A map that is modelled in this way, is one large vector with a value
<code class=
"computeroutput"><span class=
"identifier">v
</span></code> for every key
<code class=
"computeroutput"><span class=
"identifier">k
</span></code>
392 of it's domain type
<code class=
"computeroutput"><span class=
"identifier">DomainT
</span></code>.
393 But only non-identity values are actually stored. This is the motivation
394 for the definedness-Trait on
<code class=
"computeroutput"><span class=
"identifier">icl
</span>
395 <span class=
"identifier">Maps
</span></code>.
398 A
<span class=
"emphasis"><em><span class=
"bold"><strong>partial
</strong></span></em></span> map models
399 the intuitive view that only value pairs are existent, that are stored in
400 the map. A
<span class=
"emphasis"><em><span class=
"bold"><strong>total
</strong></span></em></span> map
401 exploits the possibility that all value pairs that are not stored can be
402 considered as being existent and
<span class=
"emphasis"><em><span class=
"bold"><strong>quantified
</strong></span></em></span>
403 with the identity element.
405 <a name=
"boost_icl.concepts.map_traits.pragmatical_aspects_of_map_traits"></a><h5>
406 <a name=
"id1082892"></a>
407 <a class=
"link" href=
"map_traits.html#boost_icl.concepts.map_traits.pragmatical_aspects_of_map_traits">Pragmatical
408 Aspects of Map Traits
</a>
411 From a pragmatic perspective value pairs that carry
<code class=
"computeroutput"><span class=
"identifier">identity
</span>
412 <span class=
"identifier">elements
</span></code> as mapped values can often
413 be ignored. If we count, for instance, the number of overlaps of inserted
414 intervals in an
<code class=
"computeroutput"><a class=
"link" href=
"../../boost/icl/interval_map.html" title=
"Class template interval_map">interval_map
</a></code>
415 (see example
<a class=
"link" href=
"../examples/overlap_counter.html" title=
"Overlap counter">overlap counter
</a>),
416 most of the time, we are not interested in whether an overlap has been counted
417 <code class=
"computeroutput"><span class=
"number">0</span></code> times or has not been counted
418 at all. A identity enricher map is only needed, if we want to distinct between
419 non-existence and
0-quantification.
422 The following distinction can
<span class=
"bold"><strong>not
</strong></span> be made
423 for a
<code class=
"computeroutput"><a class=
"link" href=
"../../boost/icl/partial_absorber.html" title=
"Struct partial_absorber">partial_absorber
</a></code>
424 map but it can be made for an
<code class=
"computeroutput"><a class=
"link" href=
"../../boost/icl/partial_enricher.html" title=
"Struct partial_enricher">partial_enricher
</a></code>
427 <pre class=
"programlisting">(k,v) does not exist in the map: Pair (k,v) has NOT been dealt with
428 (k,
0) key k carries
0 : Pair (k,v) has been dealt with resulting in v=
0
431 Sometimes this subtle distinction is needed. Then a
<code class=
"computeroutput"><a class=
"link" href=
"../../boost/icl/partial_enricher.html" title=
"Struct partial_enricher">partial_enricher
</a></code>
432 is the right choice. Also, If we want to give two
<code class=
"computeroutput"><span class=
"identifier">icl
</span><span class=
"special">::
</span><span class=
"identifier">Maps
</span></code>
433 a common set of keys in order to, say, iterate synchronously over both maps,
434 we need
<span class=
"emphasis"><em>enrichers
</em></span>.
437 <table xmlns:
rev=
"http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width=
"100%"><tr>
438 <td align=
"left"></td>
439 <td align=
"right"><div class=
"copyright-footer">Copyright
© 2007 -
2010 Joachim Faulhaber
<br>Copyright
© 1999 -
2006 Cortex Software GmbH
<p>
440 Distributed under the Boost Software License, Version
1.0. (See accompanying
441 file LICENSE_1_0.txt or copy at
<a href=
"http://www.boost.org/LICENSE_1_0.txt" target=
"_top">http://www.boost.org/LICENSE_1_0.txt
</a>)
446 <div class=
"spirit-nav">
447 <a accesskey=
"p" href=
"aggrovering.html"><img src=
"../../../../../../doc/src/images/prev.png" alt=
"Prev"></a><a accesskey=
"u" href=
"../concepts.html"><img src=
"../../../../../../doc/src/images/up.png" alt=
"Up"></a><a accesskey=
"h" href=
"../../index.html"><img src=
"../../../../../../doc/src/images/home.png" alt=
"Home"></a><a accesskey=
"n" href=
"../semantics.html"><img src=
"../../../../../../doc/src/images/next.png" alt=
"Next"></a>