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

[/
    Copyright (c) 2008-2010 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)
]


[/ //= Symmetric Difference ===================================================]
[section Symmetric Difference]

[section Synopsis][/ Symmetric difference]

[table
[[Symmetric difference]         [__ch_itv_sets__][__ch_itv_maps__][__ch_ele_sets__][__ch_ele_maps__] ]

[[`T& T::flip(const P&)`]                      [__ei]     [__bp]   [ ]     [__b]     ]
[[`T& flip(T&, const P&)`]                     [__ei]     [__bp]   [__e]   [__b]     ]
[[`T& operator ^=(T&, const P&)`]              [__eiS]    [__bpM]  [__es]  [__bm]    ]
[[`T  operator ^ (T, const P&)`\n
  `T  operator ^ (const P&, T)`]               [__eiS]    [__bpM]  [__es]  [__bm]    ]

]

Functions and operators that implement ['*symmetric difference*] on *icl* objects
are given in the table above.

[table
[[]      [Description of symmetric difference]]
[[`Sets`][`operator ^` implements ['*set symmetric difference*]]]
[[`Maps`][`operator ^` implements a ['*map symmetric difference*] 
          function similar to /set symmetric difference/.
          All pairs that are common to both arguments are removed. All others unified.
         ]]
]


[endsect][/ Synopsis Symmetric difference]

[section Functions][/ Symmetric difference]

/Symmetric difference/ is implemented on interval containers
by the function `T& flip(T&, const P& operand)`.

``
flip(y,x)
`` 

deletes every element of `y`, 
if it is contained in `x`. Elements of
`x` not contained in `y` are added.
For icl containers flip is also availabel as memeber function
`T& T::flip(const P& operand)`.

[/ paratract, surtract, symetract, topple, symmetric_subtract]

The admissible combinations of types for member function 
`T& T::flip(const P&)` can be summarized in the 
['*overload table*] below:

``
/* overload table for */           T\P| e i b p  
T& T::flip(const P&)               ---+--------
T& flip(T&, const P&)               s | s
                                    m |     m
                                    S | S S     
                                    M |     M M
``

The next table contains complexity characteristics for functions `flip`.

[table Time Complexity for member functions flip on icl containers
[[`T& T::flip(const P&)`\n
  `T& flip(T&, const P&)`]     [__ch_dom_t__][__ch_itv_t__][__ch_dom_mp_t__][__ch_itv_mp_t__]]
[[__icl_set__]                 [__Olgn__] []          []        []          ]
[[__icl_map__]                 []         []          [__Olgn__][]          ]
[[__itv_set__\n__sep_itv_set__][__Olgn__] [__On__]    []        []          ]
[[__spl_itv_set__]             [__Olgn__] [__On__]    []        []          ]
[[__itv_map__\n__spl_itv_map__][]         []          [__Olgn__][__On__]    ]
]

[endsect][/ Member functions Symmetric difference]


[section Inplace operators][/ Symmetric Difference]

The overload tables below are giving admissible
type combinations for `operator ^=`
that implements ['*symmetric difference*].

``
// overload tables for             element containers:     interval containers:
T& operator ^= (T&, const P&)      ^= | e b s m            ^= | e i b p S M    
                                   ---+--------            ---+------------    
                                   s  | s   s              S  | S S     S      
                                   m  |   m   m            M  |     M M   M    
``
Complexity characteristics for inplace operators
that implement ['*symmetric difference*]
are given by the next tables where 
``
n = iterative_size(y);
m = iterative_size(x); //if P is a container
``

[table Time Complexity for inplace symmetric difference on element containers
[[`T& operator &= (T& y, const P& x)`][__ch_dom_t__][__ch_dom_mp_t__][__ch_icl_set__][__ch_icl_map__]]
[[__icl_set__]                    [__Olgn__]    []               [__Omlgn__]     []              ]
[[__icl_map__]                    [__Olgn__]    [__Olgn__]       [__Omlgn__]     [__Omlgn__]     ]
]

[table Time Complexity for inplace symmetric difference on interval containers
[[`T& operator &= (T&, const P&)`][__ch_dom_t__][__ch_itv_t__][__ch_dom_mp_t__][__ch_itv_mp_t__][__ch_itv_sets__][__ch_itv_maps__]]
[[interval_sets]                  [__Olgn__]    [__On__]      []               []               [__Omlgnpm__]    []               ]
[[interval_maps]                  [__Olgn__]    [__On__]      [__Olgn__]       [__On__]         [__Omlgnpm__]    [__Omlgnpm__]    ]
]

[endsect][/ Inplace operators Symmetric Difference]

[section Infix operators][/ Symmetric Difference]

For the infix version of symmetric difference the
following overloads are available:

``
// overload tables for             element containers:     interval containers:
T operator ^ (T, const P&)         ^  | e b s m            ^  | e  i  b  p  S1 S2 S3 M1 M3
T operator ^ (const P&, T)         ---+--------            ---+---------------------------
                                   e  |     s              e  |             S1 S2 S3
                                   b  |       m            i  |             S1 S2 S3
                                   s  | s   s              b  |                      M1 M3
                                   m  |   m   m            p  |                      M1 M3
                                                           S1 | S1 S1       S1 S2 S3
                                                           S2 | S2 S2       S2 S2 S3
                                                           S3 | S3 S3       S3 S3 S3
                                                           M1 |       M1 M1          M1 M3
                                                           M3 |       M3 M3          M3 M3
``

To resolve ambiguities among interval containers
the ['*finer*] container type is chosen as result type.

[endsect][/ Infix operators Symmetric Difference]


['*See also . . .*]
[table
[]
[[[link boost_icl.function_reference.intersection ['*Intersection*]] ]]
[[[link boost_icl.function_reference.subtraction  ['*Subtraction*]]  ]]
[[[link boost_icl.function_reference.addition     ['*Addition*]]     ]]
]
['*Back to section . . .*]
[table
[]
[[[link function_synopsis_table ['*Function Synopsis*]]    ]]
[[[link boost_icl.interface ['*Interface*]]                ]]
]

[endsect][/ Symmetric Difference]
Commit	Line	Data
7c673cae FG	1	[/
	2	Copyright (c) 2008-2010 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	[/ //= Symmetric Difference ===================================================]
	11	[section Symmetric Difference]
	12
	13	[section Synopsis][/ Symmetric difference]
	14
	15	[table
	16	[[Symmetric difference] [__ch_itv_sets__][__ch_itv_maps__][__ch_ele_sets__][__ch_ele_maps__] ]
	17
	18	[[`T& T::flip(const P&)`] [__ei] [__bp] [ ] [__b] ]
	19	[[`T& flip(T&, const P&)`] [__ei] [__bp] [__e] [__b] ]
	20	[[`T& operator ^=(T&, const P&)`] [__eiS] [__bpM] [__es] [__bm] ]
	21	[[`T operator ^ (T, const P&)`\n
	22	`T operator ^ (const P&, T)`] [__eiS] [__bpM] [__es] [__bm] ]
	23
	24	]
	25
	26	Functions and operators that implement ['symmetric difference] on icl objects
	27	are given in the table above.
	28
	29	[table
	30	[[] [Description of symmetric difference]]
	31	[[`Sets`][`operator ^` implements ['set symmetric difference]]]
	32	[[`Maps`][`operator ^` implements a ['map symmetric difference]
	33	function similar to /set symmetric difference/.
	34	All pairs that are common to both arguments are removed. All others unified.
	35	]]
	36	]
	37
	38
	39	[endsect][/ Synopsis Symmetric difference]
	40
	41	[section Functions][/ Symmetric difference]
	42
	43	/Symmetric difference/ is implemented on interval containers
	44	by the function `T& flip(T&, const P& operand)`.
	45
	46	``
	47	flip(y,x)
	48	``
	49
	50	deletes every element of `y`,
	51	if it is contained in `x`. Elements of
	52	`x` not contained in `y` are added.
	53	For icl containers flip is also availabel as memeber function
	54	`T& T::flip(const P& operand)`.
	55
	56	[/ paratract, surtract, symetract, topple, symmetric_subtract]
	57
	58	The admissible combinations of types for member function
	59	`T& T::flip(const P&)` can be summarized in the
	60	['overload table] below:
	61
	62	``
	63	/* overload table for */ T\P\| e i b p
	64	T& T::flip(const P&) ---+--------
65	T& flip(T&, const P&) s \| s
66	m \| m
67	S \| S S
68	M \| M M
69	``
70
71	The next table contains complexity characteristics for functions `flip`.
72
73	[table Time Complexity for member functions flip on icl containers
74	[[`T& T::flip(const P&)`\n
75	`T& flip(T&, const P&)`] [__ch_dom_t__][__ch_itv_t__][__ch_dom_mp_t__][__ch_itv_mp_t__]]
76	[[__icl_set__] [__Olgn__] [] [] [] ]
77	[[__icl_map__] [] [] [__Olgn__][] ]
78	[[__itv_set__\n__sep_itv_set__][__Olgn__] [__On__] [] [] ]
79	[[__spl_itv_set__] [__Olgn__] [__On__] [] [] ]
80	[[__itv_map__\n__spl_itv_map__][] [] [__Olgn__][__On__] ]
81	]
82
83	[endsect][/ Member functions Symmetric difference]
84
85
86	[section Inplace operators][/ Symmetric Difference]
87
88	The overload tables below are giving admissible
89	type combinations for `operator ^=`
90	that implements ['symmetric difference].
91
92	``
93	// overload tables for element containers: interval containers:
94	T& operator ^= (T&, const P&) ^= \| e b s m ^= \| e i b p S M
95	---+-------- ---+------------
96	s \| s s S \| S S S
97	m \| m m M \| M M M
98	``
99	Complexity characteristics for inplace operators
100	that implement ['symmetric difference]
101	are given by the next tables where
102	``
103	n = iterative_size(y);
104	m = iterative_size(x); //if P is a container
105	``
106
107	[table Time Complexity for inplace symmetric difference on element containers
108	[[`T& operator &= (T& y, const P& x)`][__ch_dom_t__][__ch_dom_mp_t__][__ch_icl_set__][__ch_icl_map__]]
109	[[__icl_set__] [__Olgn__] [] [__Omlgn__] [] ]
110	[[__icl_map__] [__Olgn__] [__Olgn__] [__Omlgn__] [__Omlgn__] ]
111	]
112
113	[table Time Complexity for inplace symmetric difference on interval containers
114	[[`T& operator &= (T&, const P&)`][__ch_dom_t__][__ch_itv_t__][__ch_dom_mp_t__][__ch_itv_mp_t__][__ch_itv_sets__][__ch_itv_maps__]]
115	[[interval_sets] [__Olgn__] [__On__] [] [] [__Omlgnpm__] [] ]
116	[[interval_maps] [__Olgn__] [__On__] [__Olgn__] [__On__] [__Omlgnpm__] [__Omlgnpm__] ]
117	]
118
119	[endsect][/ Inplace operators Symmetric Difference]
120
121	[section Infix operators][/ Symmetric Difference]
122
123	For the infix version of symmetric difference the
124	following overloads are available:
125
126	``
127	// overload tables for element containers: interval containers:
128	T operator ^ (T, const P&) ^ \| e b s m ^ \| e i b p S1 S2 S3 M1 M3
129	T operator ^ (const P&, T) ---+-------- ---+---------------------------
130	e \| s e \| S1 S2 S3
131	b \| m i \| S1 S2 S3
132	s \| s s b \| M1 M3
133	m \| m m p \| M1 M3
134	S1 \| S1 S1 S1 S2 S3
135	S2 \| S2 S2 S2 S2 S3
136	S3 \| S3 S3 S3 S3 S3
137	M1 \| M1 M1 M1 M3
138	M3 \| M3 M3 M3 M3
139	``
140
141	To resolve ambiguities among interval containers
142	the ['finer] container type is chosen as result type.
143
144	[endsect][/ Infix operators Symmetric Difference]
145
146
147	['See also . . .]
148	[table
149	[]
150	[[[link boost_icl.function_reference.intersection ['Intersection]] ]]
151	[[[link boost_icl.function_reference.subtraction ['Subtraction]] ]]
152	[[[link boost_icl.function_reference.addition ['Addition]] ]]
153	]
154	['Back to section . . .]
155	[table
156	[]
157	[[[link function_synopsis_table ['Function Synopsis]] ]]
158	[[[link boost_icl.interface ['Interface]] ]]
159	]
160
161	[endsect][/ Symmetric Difference]
162
163