ceph/src/boost/libs/icl/doc/functions_interval_construct.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 [/ //= Interval Construction ===================================================================]
  11 [section Interval Construction]
  12
  13 [table
  14 [[T]                                       [__ch_dsc_itv__] [__ch_cnt_itv__] [__ch_ro_itv__] [__ch_lo_itv__]  [__ch_cl_itv__] [__ch_op_itv__]      ]
  15 [[Interval bounds]                                     [dynamic]  [dynamic]    [static]     [static]     [static]    [static]    ]
  16 [[Form]                                                [ ]        [ ]          [asymmetric] [asymmetric] [symmetric] [symmetric] ]
  17 [[['*Construct*]]                                      [ ]        [ ]          [ ]          [ ]          [ ]         [ ]         ]
  18 [[`T singleton(const P&)`]                             [__d]      [__c]        [__d]        [__d]        [__d]       [__d]       ]
  19 [[`T construct(const P&, const P&)`]                   [__d]      [__c]        [__dc]       [__dc]       [__d]       [__d]       ]
  20 [[``
  21 T construct(const P&, const P&,
  22             interval_bounds   )
  23 ``]                                                    [__d]      [__c]        [ ]          [ ]          [ ]         [ ]         ]
  24 [[`T hull(const P&, const P&)`]                        [__d]      [__c]        [__dc]       [__dc]       [__d]       [__d]       ]
  25 [[`T span(const P&, const P&)`]                        [__d]      [__c]        [__dc]       [__dc]       [__d]       [__d]       ]
  26 [[`static T right_open(const P&, const P&)`]           [__d]      [__c]        [ ]          [ ]          [ ]         [ ]         ]
  27 [[`static T left_open(const P&, const P&)`]            [__d]      [__c]        [ ]          [ ]          [ ]         [ ]         ]
  28 [[`static T closed(const P&, const P&)`]               [__d]      [__c]        [ ]          [ ]          [ ]         [ ]         ]
  29 [[`static T open(const P&, const P&)`]                 [__d]      [__c]        [ ]          [ ]          [ ]         [ ]         ]
  30 ]
  31
  32 The table above shows the availability of functions, that allow the construction
  33 of intervals. All interval constructin functins are of ['*constant time and space complexity*].
  34
  35 [table
  36 [[['*Construct*]]                                      [Description]         ]
  37 [[`T singleton(const P& value)`]                       [Constructs an interval that contains exactly one element `value`.
  38                                                         For all interval types of the icl sigletons can be constructed
  39                                                         for /discrete/ domain types. For continuous domain types, only
  40                                                         __ct_itv__ is capable to construct a singleton. ]       ]
  41 [[`T construct(const P& lower, const P& upper)`]       [Contructs an interval with lower bound `lower` and upper bound `upper` ] ]
  42 [[``
  43 T construct(const P& lower, const P& upper,
  44             interval_bounds bounds
  45             = interval_bounds::right_open())
  46 ``]
  47                                                        [For dynamically bounded intervals this function constructs an
  48                                                         interval with interval bounds specified by the third parameter. ]     ]
  49 [[`T hull(const P& x1, const P& x2)`]                  [`hull(x1,x2)` constructs the smallest interval that contains both `x1` and `x2`.
  50                                                         `x2` may be smaller than `x1`. ]       ]
  51 [[`T span(const P& x1, const P& x2)`]                  [`span(x1,x2)` constructs the interval `construct(min(x1,x2), max(x1,x2))`.
  52                                                         Note the differences between `span`, `hull` and `construct`:
  53 ``
  54 span<right_open_interval<int> >(2,1)      == [1,2) // does NOT contain 2
  55 hull<right_open_interval<int> >(2,1)      == [1,3) // contains 2
  56 construct<right_open_interval<int> >(2,1) == [)    // is empty
  57 ``
  58                                                                    ]   ]
  59 [[``
  60 static T right_open(const P&, const P&)
  61 static T left_open(const P&, const P&)
  62 static T closed(const P&, const P&)
  63 static T open(const P&, const P&)
  64 ``                                       ]             [For dynamically bounded intervals there are for static functions to
  65                                                         construct intervals with the four interval bound types:
  66 ``
  67 discrete_interval<int>      itv1 = discrete_interval<int>::closed(0,42);
  68 continuous_interval<double> itv2 = continuous_interval<double>::right_open(0.0, 1.0);
  69 ``
  70                                                                ]         ]
  71 [[['*Using the interval default*]]                     [ ]]
  72 [[`interval<P>::type`]                                 [There is a library default, for all interval containers of the *icl*.
  73                                                         The intension of the library default is to minimize the need for parameter
  74                                                         specification, when working with *icl* class templates.
  75                                                         We can get the library default interval type as `interval<P>::type`.
  76                                                         The library default uses ['*dynamically bounded intervals*]. You
  77                                                         can switch to ['*statically bounded intervals*] by
  78                                                         `#define BOOST_ICL_USE_STATIC_BOUNDED_INTERVALS` prior to icl includes. ]]
  79 [[``
  80 static T right_open(const P&, const P&)
  81 static T left_open(const P&, const P&)
  82 static T closed(const P&, const P&)
  83 static T open(const P&, const P&)
  84 ``                                     ]               [For template struct `interval` that always uses the library default
  85                                                         the static functions for the four interval bound types are also available.
  86 ``
  87 interval<int>::type    itv1 = interval<int>::closed(0,42);
  88 interval<double>::type itv2 = interval<double>::right_open(0.0, 1.0);
  89 ``
  90                                                         This works with the statically bounded intervals as well,
  91                                                         with the restriction that for continuous domain types the
  92                                                         matching function has to be used:
  93 ``
  94 #define BOOST_ICL_USE_STATIC_BOUNDED_INTERVALS
  95 . . .
  96 // library default is the statically bounded right_open_interval
  97 interval<int>::type    itv1 = interval<int>::closed(0,42); //==[0,43) //ok, bounds are shifted
  98 interval<double>::type itv2 = interval<double>::right_open(0.0, 1.0); //ok. right_open matches
  99 interval<double>::type itv3 = interval<double>::closed(0.0, 1.0);     //will NOT compile
 100 ``
 101                                                         See also examples
 102                                                         [link boost_icl.examples.dynamic_interval Dynamic intervals] and
 103                                                         [link boost_icl.examples.static_interval Static intervals]
 104                                                         ]]
 105 ]
 106
 107 ['*See also . . .*]
 108 [table
 109 []
 110 [[[link boost_icl.examples.dynamic_interval ['*Example: Dynamically bounded intervals and the library default*]] ]]
 111 [[[link boost_icl.examples.static_interval  ['*Example: Statically bounded intervals, changing the library default*]] ]]
 112 ]
 113
 114 ['*Back to section . . .*]
 115 [table
 116 []
 117 [[[link additional_interval_functions ['*Additional interval functions*]] ]]
 118 [[[link function_synopsis_table ['*Function Synopsis*]]          ]]
 119 [[[link boost_icl.interface ['*Interface*]]                      ]]
 120 ]
 121
 122 [endsect][/ Interval Construction]
 123
 124