add docu

Doc/tutorial_12.docu

@@ -0,0 +1,38 @@
+/** \page tutorial_12 Filtering ranges with predicates
+
+This examples shows:
+- How to use predicates to filter which elements of a mesh you want iterate over
+
+In the previous tutorial we discussed already that the ranges returned by functions like all_vertices(), voh_range() or outgoing_halfedges() provide a few helpful methods such as avg() or to_vector(). Another interesting method is filtered() which requires as argument something that can be called for an element of the range and returns a bool. The resulting range will then only iterate over elements for which the filter returs true.
+The filter can be a lambda, a function pointer, a property manager holding a bool property, or a functor object such as the predicates defined in <OpenMesh/Core/Utils/Predicates.hh>. The predefined predicates can check the status of a mesh element and test if they are boundary.
+With their help you can for example count all boundary vertices:
+
+\dontinclude 12-predicates/predicates.cc
+\skipline Count boundary vertices
+\until boundary vertices
+
+Predicates can be composed using the operators ||, &&, and !. This enables you to specify precisely which elements you want process in your loop, e.g. inner vertices that are selected:
+
+\skipline Selected inner vertices
+\until std::cout << std::endl
+
+As mentioned above, the filter argument can be anything returning a bool for a given input, e.g. a function pointer:
+
+\skipline Faces whose id is divisible by 3
+\until faces whose id is divisible by 3
+
+However, function pointers, lambdas etc are not composable. Fortunately, you can use make_predicate to turn them into composable predicates:
+
+
+\skipline Faces which are tagged or whose id is not divisible by 3
+\until faces which are tagged or whose id is not divisible by 3
+
+Below is the complete source code:
+
+\include 12-predicates/predicates.cc
+
+---
+
+
+
+*/