Debian Codegraph @

doc/manual2/concepts

raw
1 h1. Concept Checking
2
3 The C++ Standard Template Library introduces the notion of _concepts_,
4 which specify families of types related by a common interface. In
5 template-based programming with the STL, concepts serve a similar
6 purpose to type classes in Haskell. While, unlike Haskell's language-level
7 support for type classes, concept-checking is not directly supported by the
8 C++ compiler or language, C++ libraries have been written which use template
9 techniques to provide compile-time checking and enforcement of concepts.
10 We use the Boost Concept Checking library.
11
12 h2. Lib2geom's 'Concepts'
13
14 There are several important lib2geom 'concepts'.
15
16 h3. *FragmentConcept*
17
18 This is perhaps the most important concept within lib2geom, as it defines
19 the interface for the basic, one-dimensional functions. Fragments are
20 defined on the interval [0,1], which is referred to as the _intended domain_
21 of the function. Functions may be well defined for all values (many are),
22 but the 0-to-1 domain has significant semantic value. When the functions
23 are used to represent a *Curve*, 0 is the start and 1 is the end.
24
25 h4. @ T::output_type @
26
27 Every fragment must typedef an *output_type*. This is usually *Coord*, however,
28 in order to support considering @D2<T>@ a fragment, this typedef was added.
29 This information is also used by the compiler to infer the proper bounds and
30 sbasis types.
31
32 h4. Value Query
33
34 <pre><code>
35 output_type T::valueAt(double);
36 output_type T::operator()(double);
37 output_type T::at0();
38 output_type T::at1();
39 </code></pre>
40
41 *FragmentConcept* defines several methods for retrieving the value at a point.
42 One method is to use the *valueAt* function, which returns output_type given
43 a t-value. Fragments are also functors, which in C++ lingo means they look
44 like function calls, as they overload the () operator. This is essentially
45 the same as calling valueAt. The functions *at0* and *at1* are also
46 provided, and should be used whenever the start or end of the function is
47 required, as many functions directly store this information.
48
49 h4. @ sbasis_type T::toSBasis() @
50
51 As *SBasis* will be the main function representation, it is desirable to always
52 be able to approximate and deal with other functions in this way. Therefore,
53 the *toSBasis* function is required. When *output_type* is @double@,
54 @sbasis_type@ is *SBasis*. When *output_type* is *Point*, @sbasis_type@ is
55 *SBasisCurve*.
56
57 (TODO: in writing this it occurs to me that toSBasis should take a tolerance)
58
59 h4. @ T reverse(T) @
60
61 As most of the implementors of fragment consider functions in a fairly
62 symmetric way, the *reverse* function was included in the *FragmentConcept*.
63 *reverse* flips the function's domain on 0.5, such that f'(t) = f(1-t).
64
65 h4. Bounds
66
67 <code><pre>
68 bounds_type bounds_fast(T);
69 bounds_type bounds_exact(T);
70 bounds_type bounds_local(T, Interval);
71 </pre></code>
72
73 Finding the bounds of a function is essential for many optimizations and
74 algorithms. This is why we provide 3 functions to do it. *bounds_fast*
75 provides a quick bounds which contains the actual bounds of the function.
76 This form is ideal for optimization, as it hopefully does not require too
77 much computation. *bounds_exact*, on the other hand, provides the exact
78 bounds of the function. *bounds_local* only returns the bounds of an
79 interval on the function - at the moment it is unclear if this is exact.
80 When *output_type* is @double@, @bounds_type@ is *Interval*. When
81 *output_type* is @Point@, @bounds_type@ is *Rect*.
82
83 See the linear.h code for an example of an implementation of *FragmentConcept*.
84
85 h3. *OffsetableConcept*
86
87 *OffsetableConcept* defines what it means to be offsetable. Like
88 *FragmentConcept*, this concept requires an output_type, which is used
89 as the offset type. This still makes since when the implementor is
90 also a fragment, as in pretty much all cases you would want to offset
91 a function using the same type it outputs.
92
93 The following operators are defined by *OffsetableConcept*:
94
95 @T + output_type, T - output_type, T += output_type, T -= output_type@,
96
97 h3. *ScalableConcept*
98
99 *ScalableConcept* defines what it means to be scalable. Like
100 *OffsetableConcept*, it requires an output_type, which is used as the
101 scalar-type. This is an assumption that may not pan out in the future,
102 however, for all function types we've used this always applies.
103 Technically points should not be multiplicable, however, they provide a
104 convenient storage mechanism for non-uniform scaling. If this changes
105 in the future, the implementations will remain the same, while the
106 concept definitions are loosened.
107
108 The following operators are defined by *ScalableConcept*:
109 @T * scalar_type, T / scalar_type, T *= scalar_type, T /= scalar_type, -x@,
110
111 h3. *AddableConcept*
112
113 *AddableConcept* defines a concept for classes which are closed under
114 addition (the classes may be added to themselves, and the result is the
115 same type). The following operators are included:
116
117 @x + y, x - y, x += y, x -= y@
118
119 h3. *MultiplicableConcept*
120
121 *MultiplicableConcept* defines a concept for classes which are closed under
122 multiplication (the classes may be multiplied by themselves, and the result
123 is the same type). The following operators are included:
124
125 @x * y, x *= y@
126
127 At some point a DividableConcept may be implemented, however, at the moment
128 it is not very useful.