ceph/src/boost/libs/icl/doc/functions_symmetric_difference.qbk

   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