| 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. |