[ceph.git] / ceph / src / boost / libs / icl / doc / functions_interval_construct.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)
]


[/ //= Interval Construction ===================================================================]
[section Interval Construction]

[table
[[T]                                       [__ch_dsc_itv__] [__ch_cnt_itv__] [__ch_ro_itv__] [__ch_lo_itv__]  [__ch_cl_itv__] [__ch_op_itv__]      ]
[[Interval bounds]                                     [dynamic]  [dynamic]    [static]     [static]     [static]    [static]    ]
[[Form]                                                [ ]        [ ]          [asymmetric] [asymmetric] [symmetric] [symmetric] ]
[[['*Construct*]]                                      [ ]        [ ]          [ ]          [ ]          [ ]         [ ]         ]
[[`T singleton(const P&)`]                             [__d]      [__c]        [__d]        [__d]        [__d]       [__d]       ]
[[`T construct(const P&, const P&)`]                   [__d]      [__c]        [__dc]       [__dc]       [__d]       [__d]       ]
[[``
T construct(const P&, const P&, 
            interval_bounds   )
``]                                                    [__d]      [__c]        [ ]          [ ]          [ ]         [ ]         ]
[[`T hull(const P&, const P&)`]                        [__d]      [__c]        [__dc]       [__dc]       [__d]       [__d]       ]
[[`T span(const P&, const P&)`]                        [__d]      [__c]        [__dc]       [__dc]       [__d]       [__d]       ]
[[`static T right_open(const P&, const P&)`]           [__d]      [__c]        [ ]          [ ]          [ ]         [ ]         ]
[[`static T left_open(const P&, const P&)`]            [__d]      [__c]        [ ]          [ ]          [ ]         [ ]         ]
[[`static T closed(const P&, const P&)`]               [__d]      [__c]        [ ]          [ ]          [ ]         [ ]         ]
[[`static T open(const P&, const P&)`]                 [__d]      [__c]        [ ]          [ ]          [ ]         [ ]         ]
]

The table above shows the availability of functions, that allow the construction
of intervals. All interval constructin functins are of ['*constant time and space complexity*].

[table
[[['*Construct*]]                                      [Description]         ]
[[`T singleton(const P& value)`]                       [Constructs an interval that contains exactly one element `value`. 
                                                        For all interval types of the icl sigletons can be constructed
                                                        for /discrete/ domain types. For continuous domain types, only
                                                        __ct_itv__ is capable to construct a singleton. ]       ]
[[`T construct(const P& lower, const P& upper)`]       [Contructs an interval with lower bound `lower` and upper bound `upper` ] ]
[[``
T construct(const P& lower, const P& upper,
            interval_bounds bounds 
            = interval_bounds::right_open())
``]  
                                                       [For dynamically bounded intervals this function constructs an
                                                        interval with interval bounds specified by the third parameter. ]     ]
[[`T hull(const P& x1, const P& x2)`]                  [`hull(x1,x2)` constructs the smallest interval that contains both `x1` and `x2`.
                                                        `x2` may be smaller than `x1`. ]       ]
[[`T span(const P& x1, const P& x2)`]                  [`span(x1,x2)` constructs the interval `construct(min(x1,x2), max(x1,x2))`.
                                                        Note the differences between `span`, `hull` and `construct`:
``
span<right_open_interval<int> >(2,1)      == [1,2) // does NOT contain 2
hull<right_open_interval<int> >(2,1)      == [1,3) // contains 2
construct<right_open_interval<int> >(2,1) == [)    // is empty
``                                                                   
                                                                   ]   ]
[[``
static T right_open(const P&, const P&)
static T left_open(const P&, const P&)
static T closed(const P&, const P&)
static T open(const P&, const P&)
``                                       ]             [For dynamically bounded intervals there are for static functions to
                                                        construct intervals with the four interval bound types:
``
discrete_interval<int>      itv1 = discrete_interval<int>::closed(0,42);
continuous_interval<double> itv2 = continuous_interval<double>::right_open(0.0, 1.0);
``
                                                               ]         ]
[[['*Using the interval default*]]                     [ ]]                                                        
[[`interval<P>::type`]                                 [There is a library default, for all interval containers of the *icl*.
                                                        The intension of the library default is to minimize the need for parameter
                                                        specification, when working with *icl* class templates.
                                                        We can get the library default interval type as `interval<P>::type`. 
                                                        The library default uses ['*dynamically bounded intervals*]. You
                                                        can switch to ['*statically bounded intervals*] by 
                                                        `#define BOOST_ICL_USE_STATIC_BOUNDED_INTERVALS` prior to icl includes. ]]
[[``
static T right_open(const P&, const P&)
static T left_open(const P&, const P&)
static T closed(const P&, const P&)
static T open(const P&, const P&)
``                                     ]               [For template struct `interval` that always uses the library default
                                                        the static functions for the four interval bound types are also available. 
``
interval<int>::type    itv1 = interval<int>::closed(0,42);
interval<double>::type itv2 = interval<double>::right_open(0.0, 1.0);
``
                                                        This works with the statically bounded intervals as well, 
                                                        with the restriction that for continuous domain types the 
                                                        matching function has to be used:
``
#define BOOST_ICL_USE_STATIC_BOUNDED_INTERVALS
. . .
// library default is the statically bounded right_open_interval
interval<int>::type    itv1 = interval<int>::closed(0,42); //==[0,43) //ok, bounds are shifted
interval<double>::type itv2 = interval<double>::right_open(0.0, 1.0); //ok. right_open matches
interval<double>::type itv3 = interval<double>::closed(0.0, 1.0);     //will NOT compile
``
                                                        See also examples 
                                                        [link boost_icl.examples.dynamic_interval Dynamic intervals] and
                                                        [link boost_icl.examples.static_interval Static intervals]   
                                                        ]]
] 

['*See also . . .*]
[table
[]
[[[link boost_icl.examples.dynamic_interval ['*Example: Dynamically bounded intervals and the library default*]] ]]
[[[link boost_icl.examples.static_interval  ['*Example: Statically bounded intervals, changing the library default*]] ]]
]

['*Back to section . . .*]
[table
[]
[[[link additional_interval_functions ['*Additional interval functions*]] ]]
[[[link function_synopsis_table ['*Function Synopsis*]]          ]]
[[[link boost_icl.interface ['*Interface*]]                      ]]
]

[endsect][/ Interval Construction]
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	[/ //= 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