Guidelines for writing generic functions¶
This section contains more advanced technical details about the implementation of vectors and views in vif. It also includes tips and tricks for writing correct, efficient, and generic functions.
What is a generic function?¶
A “generic” function can operate on vectors regardless of the precise type of their elements. For example, a function to shuffle the values inside a vector does not care whether these values are integers, strings, or potatoes, it just needs to know how many values there are.
In C++, such generic functions are written using template metaprogramming:
template<typename T>
void foo(const T& v) {
print(v(1,_)*2.5);
}
vec2f v1 = {{1.0}, {5.0}, {-1.0}}; // float, shape 3x1
foo(v1); // prints {12.5}
vec2i v2 = {{1, 5}, {-1, 1}}; // int, shape 2x2
foo(v2); // prints {-2.5, 2.5}
Note
This example uses the print() function from the vif support library, which simply displays its arguments on the terminal.
Summary of guidelines¶
The functions we use as examples here can be somewhat silly, but they will serve to illustrate a number of important “rules” which one should follow when writing generic functions. These rules are explained in detail below, and can be summarized as follows:
- Use the most specific type possible for the function arguments (e.g.,
vec<1,T>instead of justT). - Even when the function is supposed to work on only one specific data type, leave the data type of vectors unconstrained in order to support both vectors and view (e.g.,
vec<D,T>instead ofvec<D,int>). - Use
std::enable_if<>to express any remaining constraints on the type. - Do not use the
Tinvec<D,T>to form new variables, usemeta::rtype_t<T>instead. - Provide default values for template arguments whenever it makes sense, to enable support for initializer lists.
- Avoid output or input/output parameters whenever possible, else use universal references
T&&andstd::enable_if<>as described in the guidelines below. - Use the available helper tools to vectorize existing functions.
- Use
vif_check()to express any constraints on the data that can only be checked at run time (number of elements, value ranges, etc.).
Expressing constraints on function arguments¶
In the example above, the type of the function’s argument v is T, and is totally unconstrained. It could be anything. However this specific function has an implicit constraint on the type T: it must be possible to write v(1,_)*2.5. This means v must be a 2D vector, and the elements must be of arithmetic type. If you try to use this function on a value which does not satisfy this implicit constraint, the compiler will generate an error:
vec1f v4 = {1.0, 5.0, 6.0};
foo(v4); // error! 1D vector
The program will not compile, which is good. However the error message will be nasty (180 lines of errors with Clang), and the error will point to code inside the function. This is far from ideal, because the user of the function should not need to understand what the function does internally to fix the error. This can be fixed by adding constraints on the type T:
template<typename T>
void foo(const vec<2,T>& v) {
print(v(1,_)*2.5);
}
Here, we state that v must be a 2D vector, and we leave the type of the elements unconstrained. Using this new definition of foo(), the error message in the case above becomes much smaller (4 lines of errors), and explicitly says that there is no matching function call for foo(v4). This is much better. Therefore you should always make sure to specify as many constraints as possible in the signature of the function (i.e., the type of its arguments).
We are not done though. Indeed, we still left the type of the elements unconstrained, while we need elements of arithmetic types to be able to write v(1,_)*2.5. For example, using a vector of strings would be an error:
vec2s v5 = {{"I", "am"}, {"a", "string"}};
foo(v5); // error! vector of strings
Again, this emits a lengthy error from inside the function (20 lines of errors). We can fix this by adding extra constraints on the type T of the elements. One possibility is to force it to be some “common” type, like double:
// Note: parameter is fully constrained, it is not generic anymore
void foo(const vec<2,double>& v) {
print(v(1,_)*2.5);
}
This makes the error much easier to understand (7 lines of errors), but it has the important downside that the function is no longer generic: it needs a vector of double. If you try to call it on a vector of float, it will first have to make a copy of that vector and convert all values to double before calling the function, which is not optimal. It will also fail to work on views (see below). So unless you know the function should only be used with double values, this is not the right solution. Instead, we can leave the type of elements to be generic, and use std::enable_if<> to express a constraint on this type, in this case std::is_arithmetic<T>:
template<typename T,
typename enable = typename std::enable_if<std::is_arithmetic<T>::value>::type>
void foo(const vec<2,T>& v) {
print(v(1,_)*2.5);
}
With this version of the function, the error when called on vectors of strings becomes much clearer (4 lines of errors) and says that you cannot call the function on strings. Again, much better!
So, that’s it? Not quite. There is one last implicit requirement when we write v(1,_): the first dimension of v must have at least two elements. There is no way to check this at the time of compilation, so the faulty program below will compile:
vec2i v6;
foo(v6); // compiles, but runtime error! empty vector
It will fail at runtime though. The backtrace will show that the error happened in foo(), but with a rather cryptic error message:
error: operator(): index out of bounds (1 vs. 0)
The solution here is to perform an explicit check inside the function, and emit a clearer error message using the vif_check() function:
template<typename T,
typename enable = typename std::enable_if<std::is_arithmetic<T>::value>::type>
void foo(const vec<2,T>& v) {
vif_check(v.dims[0] >= 2, "vector must have at least two elements along first dimension ",
"(got ", v.dims[0], ")");
print(v(1,_)*2.5);
}
The error shown to the user then becomes clear:
error: vector must have at least two elements along first dimension (got 0)
Now that we do an explicit check that the index 1 is valid before accessing the vector, we no longer need the vector to perform automatic bounds checking. Therefore we can use the “safe” indexing interface:
template<typename T,
typename enable = typename std::enable_if<std::is_arithmetic<T>::value>::type>
void foo(const vec<2,T>& v) {
vif_check(v.dims[0] >= 2, "vector must have at least two elements along first dimension ",
"(got ", v.dims[0], ")");
print(v.safe(1,_)*2.5);
}
This is the optimal way to write this function, and it is clearly not as pretty as the very first version. This shows that, while writing generic functions is easy, writing them well is much harder. For this reason, always check in the support library if a function already exists before writing your own.
It should be said, however, that the very first version we wrote actually does the work we expect it to do (save for the fact that it does not support initializer lists, see below). It is not “incorrect”; its only defect is that it will not be very helpful when things go wrong.
Supporting initializer lists¶
There is one last modification we can do to make the foo() function “as good as it gets”. Indeed, even with the last version, we cannot use initializer lists directly as function arguments:
foo({{1, 5}, {-1, 1}});
This generates an error because the compiler is not smart enough to infer the type T of the vector from this initializer list. Unfortunately, in general we cannot do this perfectly and support any type in the initializer list.
But we can still make it work. The trick is to specify a default value for the template parameter T, for example double. This way, the initializer list will automatically be used to form a vector of double, and the code will compile and run. This is not a perfect solution because the true type of the values in the initializer list is lost, but in most cases it is possible to identify a “safe” type (such as double) that will be able to do the job anyway.
In this particular case, double is actually a perfect choice because we multiply the values of the vector by 2.5, which requires a conversion to double anyway. So converting the values of the initializer list to double will not change the final result. The definite, final version of our function is thus:
template<typename T = double, // use a default value here
typename enable = typename std::enable_if<std::is_arithmetic<T>::value>::type>
void foo(const vec<2,T>& v) {
vif_check(v.dims[0] >= 2, "vector must have at least two elements along first dimension ",
"(got ", v.dims[0], ")");
print(v.safe(1,_)*2.5);
}
Supporting both vectors and views¶
For a vector of type vec<D1,T>, a view will have a type vec<D2,T*> or vec<D2,const T*>. The number of dimensions can be different, and the data type is a pointer to the type of elements in the vector. The const qualifier is used to propagate const-correctness if the original vector was declared const.
This makes it relatively easy to write function that work on both vectors and view, but this distinction means that there are a number a details to keep in mind. Consider this generic function that computes the sum of all the elements in a vector:
template<std::size_t D = 1, typename T = double>
T sum_it_all(const vec<D,T>& v) {
T ret = 0;
for (const T& val : v) {
ret += val;
}
return ret;
}
Note
Such a function already exists in the vif support library, and is called total() (for integers and floating point values) or count() (for boolean values). Their return type is determined in a smarter way than we discuss here, to prevent overflow and underflow.
This implementation works for all vectors, but it will fail for views. Indeed, if called on a view of type vec<1,int*>, then T = int*, and the return value is not an integer but an (invalid!) pointer to an integer. Fortunately, it will not even compile because the loop will try to assign the values of v to a const int*&, which will fail. Therefore, the type T should never be used directly like this.
Instead, you should apply the transform meta::rtype_t<T>, which essentially transforms T* into T and removes const qualifiers, and use auto whenever possible to let the type system make the right decisions for you:
template<std::size_t D = 1, typename T = double>
meta::rtype_t<T> sum_it_all(const vec<D,T>& v) {
meta::rtype_t<T> ret = 0;
for (const auto& val : v) {
ret += val;
}
return ret;
}
There are a few, rarer corner cases to keep in mind when both view and vectors need to be supported. The case of output parameters, in particular, is described further below.
Vectorizing scalar functions¶
Most function created in C++ thus far, including those in the C++ standard library, are scalar functions which operate on one single value. The best example of this are all the mathematical functions, sqrt(), pow(), ceil(), etc. These functions can be vectorized to operate directly on vector data without having to write a loop. The vif support library contains a large number of such vectorized functions:
double v1 = 2.0;
sqrt(v1); // 1.41...
vec1d v2 = {2.0, 4.0, 6.0};
sqrt(v2); // {1.41..., 2.0, 2.45...}
However the vif support library cannot contain all functions that ever existed, and you may create your own scalar functions that you wish to vectorize. This can be achieved using the preprocessor macro VIF_VECTORIZE():
float myfunc(float v) {
return sqrt(3*v + 5.0); // whatever you wish to do
}
VIF_VECTORIZE(myfunc)
The macro must be called in the global scope, inside a namespace, or a the root scope of a class. It cannot be called inside a function. This macro emits two additional functions with the same name. The first function is the most generic vectorized version of the scalar version, which will get used most of the time.
The second version offers an interesting optimization opportunity when the return type is the same as the argument type (as is the case for myfunc), and when the function is called on a temporary vector (not views). This optimized version reuses the memory of the temporary vector instead of returning a brand new vector. This offers important optimizations in case of chained calls:
vec1d v1 = {1.0, 1.2, 1.5};
vec1d v2 = myfunc(sqrt(v1));
In this example, sqrt(v1) creates a temporary vector, and myfunc() applies myfunc() in-place on the values of the temporary vector. It is equivalent to this:
vec1d v1 = {1.0, 1.2, 1.5};
vec1d tmp(v1.dims);
for (uint_t i : range(v1)) {
tmp[i] = sqrt(v1[i]);
}
for (double& v : tmp) {
v = myfunc(v);
}
vec1d v2 = std::move(tmp);
Without this optimization, the chained call would have created two temporaries:
vec1d v1 = {1.0, 1.2, 1.5};
vec1d tmp1(v1.dims);
for (uint_t i : range(v1)) {
tmp1[i] = sqrt(v1[i]);
}
vec1d tmp2(tmp1.dims);
for (uint_t i : range(tmp1)) {
tmp2[i] = myfunc(tmp1[i]);
}
vec1d v2 = std::move(tmp2);
The optimal version would avoid the extra loop:
vec1d v1 = {1.0, 1.2, 1.5};
vec1d tmp(v1.dims);
for (uint_t i : range(v1)) {
tmp[i] = myfunc(sqrt(v1[i]));
}
vec1d v2 = std::move(tmp);
This is only possible using expression templates, which currently vif does not support for the sake of simplicity. Therefore, if performances are critical you may want to write the loop explicitly (following the guidelines in Indexing for optimal performance).
A cleaner alternative is to use vectorize_lambda_first(), which transforms a lambda function into a functor with overloaded call operator that works on both vector and scalar values. It also supports the optimization for chained calls. Contrary to the VIF_VECTORIZE() macro, vectorize_lambda_first() can be called in any scope, including inside other functions:
auto chained = vectorize_lambda_first([](float f) { return myfunc(sqrt(f)); });
vec1d v1 = {1.0, 1.2, 1.5};
vec1d v2 = chained(v1);
Both VIF_VECTORIZE() and vectorize_lambda_first() will vectorize the function/lambda on the first argument only. Other arguments will simply be forwarded to all the calls, so foo(v,w) will call foo(v[i],w) for each index i in v.
If instead you need to call foo(v[i],w[i]), you should use vectorize_lambda(). This is an alternative implementation that will support vector or scalars for all its arguments, and will assume that the vectors all have the same size and should be jointly iterated. The downside of this implementation is that the chaining optimization is not available.
Output arguments and views¶
In general, the only output of a function must be its return value. Output arguments should only be used when: a) the function must return multiple values, and b) it would be inefficient or impractical to return them by value. Otherwise, one may wish to use input/output arguments for functions that have no return value but only modify the content of an existing vector. As you will see below, writing functions with output or input/output vector arguments is possible but a bit nasty, so make sure you really need them before diving in.
The typical example where output arguments are needed is the following function which converts a string to a value of another type (e.g., an integer):
template<typename T>
bool from_string(const std::string& s, T& v) {
std::istringstream ss(s);
return ss >> v;
}
Note
In C++ there is no difference between purely output parameters (only used to store a result) and input/output parameters (used to read data and write results back). As a result, even though the discussion here is centered on output parameters, the same principles apply to input/output parameters as well.
This function returns a flag to let the user know whether the conversion was successful, and the output value is stored in the argument v, which is a reference (T&). The function is then used as follows:
int v;
if (from_string("42", v)) {
// do whatever with 'v'
} else {
error("could not convert the string");
}
Note
In C++17, one may wish to return an std::optional<T> instead, which would be the optimal solution for the scalar case. However this solution does not vectorize well. Currently, vec<D,std::optional<T>> is not supported; it may work, but use it at your own risk.
The vectorization of such functions cannot be done with the automatic vectorization tools described above, so we will have to do it manually. It is rather simple, right? We only need to use a reference to an output vector vec<D,T>&:
template<std::size_t D = 1, typename U = std::string,
typename T, typename enable = typename std::enable_if<
std::is_same<meta::rtype_t<U>, std::string>::value
>::type>
vec<D,bool> from_string(const vec<D,U>& s, vec<D,T>& v) {
vec<Dim,bool> res(s.dims);
v.resize(s.dims);
for (uint_t i : range(s)) {
res.safe[i] = from_string(s.safe[i], v.safe[i]);
}
return res;
}
In this particular case, we use std::enable_if<> to make sure the input type is either a vector of strings or a view on such vector. We then return a vector of bool so the user can check the success of the conversion for each individual value separately. The function is then used as follows:
vec1s s = {"5", "-6", "9", "42"};
vec1i v;
vec1b r = from_string(s, v);
for (uint_t i : range(s)) {
if (r[i]) {
// do whatever with 'v[i]'
} else {
error("could not convert the string");
}
}
The catch here is to support views as output arguments. Indeed, one may want to convert only part of a string vector with from_string() and store the result in a view, in which case our current implementation fails:
vec1s s = {"5", "-6", "9", "42"};
// Say we only want to convert values with 2 characters
vec1u id = where(length(s) == 2);
// This does *not* work:
vec1i v(s.dims); // resize output vector beforehand
vec1b r = from_string(s[id], v[id]);
// error: 'v[id]' is an r-value, cannot bind it to a reference 'vec<D,T>&'
// But this works:
vec1i v(s.dims); // resize output vector beforehand
vec1i tmp; // create a temporary
vec1b r = from_string(s[id], tmp);
v[id] = tmp; // assign temporary values to 'v'
Note
This issue also affects IDL, in a nastier way since IDL will not throw any error. It will store the output values in a automatically generated temporary vector, which is then discarded, so the values of the view are not modified… Oops! In IDL, this can only be solved by explicitly introducing a temporary vector and assigning it back to the view, as done in the example above. But C++ is smarter, and we can make this work! Read on.
Such type of problem arises whenever you write a function that takes a non-constant reference to a vector in order to modify its values. To support this type of usage with views, we need an argument type that can be either an “l-value” (a reference to a vector) or an “r-value” (a temporary view). This is exactly what the “universal reference” is for: T&&. Unfortunately, this universal reference requires an unconstrained type T. This means we loose all the implicit constraints on the type: it is no longer vec<D,T>, but simply T. Therefore we will have to specify these constraints explicitly using std::enable_if<>. And there are a lot of constraints! We want to make sure:
- that
Tis a vector or a view, - that the number of dimensions of
Tis the same as the input vector of strings, - that if
Tis an r-value, it must be a non-constant view, - that if
Tis an l-value, it must be a non-constant reference (to a vector or a view).
Since these basic requirements will be the same for every vectorized function with output parameters, a specific trait is provided in vif to express all these constraints: meta::is_compatible_output_type<In,Out>. It is used in the following way:
template<std::size_t D = 1, typename U = std::string, typename T,
typename enable = typename std::enable_if<
std::is_same<meta::rtype_t<U>, std::string>::value && // this was there before
meta::is_compatible_output_type<vec<D,U>,T>::value // this is the new trait
>::type>
vec<D,bool> from_string(const vec<D,U>& s, T&& v) {
// ...
}
In addition, here we need to differentiate the behavior of the function for the two cases: we want the “vector” version to automatically resize the output vector to the dimensions of the input vector, and the “view” version to simply check that the view has the same dimensions as the input vector. This is expected to be a common behavior for functions with output parameters, therefore a helper function is provided in vif to do just that: meta::resize_or_check(v, d). This function resizes the vector v to the dimensions d, or, if v is a view, checks that its dimensions match d. The final, fully generic, vectorized function is therefore:
template<std::size_t D = 1, typename U = std::string, typename T,
typename enable = typename std::enable_if<
std::is_same<meta::rtype_t<U>, std::string>::value &&
meta::is_compatible_output_type<vec<D,U>,T>::value
>::type>
vec<D,bool> from_string(const vec<D,U>& s, T&& v) {
vec<Dim,bool> res(s.dims);
meta::resize_or_check(v, s.dims);
for (uint_t i : range(s)) {
res.safe[i] = from_string(s.safe[i], v.safe[i]);
}
return res;
}
If you are in a case where there is no “input” vector to consider, and you simply want to write a function that modifies an existing vector’s values (i.e., an input/output parameters), use the simpler meta::is_output_type<T> trait:
template<typename T, typename enable = typename std::enable_if<
std::is_vec<T>::value && meta::is_output_type<T>::value
>::type>
void twice(T&& v) {
v[_] *= 2;
}
This traits only checks the last two conditions of meta::is_compatible_output_type, namely:
- that if
Tis an r-value, it must be a non-constant view, - that if
Tis an l-value, it must be a non-constant reference (to a vector or a view).
Creating views¶
TODO
Metaprogramming helpers¶
TODO