Added file documentation explaining and listing the features.

utils.hpp

@@ -1,6 +1,37 @@
 #ifndef DEF_utils
 #define DEF_utils
 
+/// \file utils.hpp
+/// \brief This file is a header-only "library" of useful tools that are often needed when developping in C++.
+///
+/// The file contains the following tools (non-exhaustive list) :
+/// Macros :
+/// - `PRINT_VAR`, `PRINT_VEC`, and `PRINT_STR` macros to print the name of variables as well as the variables themselves.
+/// - `RAND_A_B`, and `RAND_0_1`, to generate double precision floating point random numbers uniformly spread over an interval (using stdlib's rand()).
+/// - `MIN` and `MAX` macros to return the min or max of two values (note that both arguments are evaluated twice).
+///
+/// Template functions :
+/// - `min` and `max` to return the min or max of two values (they are evaluated only once).
+/// - `sureAbs` to return the absolute value of a numeric type (that is never going to cast a floating point number into a integer like ::abs often does).
+/// - `clamp(x, a, b)` to constrain a value `x` to an interval [a, b].
+/// - `operator<<(std::ostream& os, const std::vector<T> & objs)` to print the contents of an std::vector to an ostream.
+/// - `operator<<(std::ostream& os, const std::list<T> & objs)` to print the contents of an std::list to an ostream.
+///
+/// Not really template functions :
+/// - `rand_xorwow` and `rand_parkmiller` to generate uniformly distributed pseudo-random numbers. Very fast. Very nice.
+///
+/// Classes :
+/// - `Chronometer` to measure execution times, with convenient macros that hide the inner workings (see documentation of `Chronometer` for more info).
+/// - `Profiler` to measure execution times of individual lines, with convenient macros that hide the inner workings (see documentation of `Profiler` for more info).
+///
+/// Some tools can be deactivated by defining the following defines BEFORE including `utils.hpp` :
+/// - UTILS_NO_RAND : Deactivates the `rand_xorwow` and `rand_parkmiller` functions. Removes the inclusion of <cstdint>.
+/// - UTILS_NO_CHRONO : Deactivates the `Chronometer` class. Removes the inclusion of the following standard headers : <iostream> <chrono> <ratio> <ctime>.
+/// - UTILS_NO_PROFILER : Deactivates the `Profiler` class. Removes the inclusion of the following standard headers : <iostream> <iomanip> <chrono> <ratio> <ctime> <cmath> <algorithm> <vector>.
+/// - UTILS_NO_OSTREAM_OPERATOR : Deactivates the `operator<<` template function for BOTH `std::vector` and `std::list`. In order to deactivate only one of the two, use `UTILS_NO_OSTREAM_OPERATOR_LIST` or `UTILS_NO_OSTREAM_OPERATOR_VECTOR`.
+/// - UTILS_NO_OSTREAM_OPERATOR_LIST : Deactivates the `operator<<` template function for `std::list` ONLY.
+/// - UTILS_NO_OSTREAM_OPERATOR_VECTOR : Deactivates the `operator<<` template function for `std::vector` ONLY.
+
 #include <ostream>
 #include <utility>
 
@@ -36,6 +67,7 @@ T clamp(const T & x, const T & a, const T & b)
 
 #ifndef UTILS_NO_OSTREAM_OPERATOR
 
+#ifndef UTILS_NO_OSTREAM_OPERATOR_VECTOR
 #include <vector>
 template<typename T>
 std::ostream& operator<<(std::ostream& os, const std::vector<T> & objs)
@@ -44,7 +76,9 @@ std::ostream& operator<<(std::ostream& os, const std::vector<T> & objs)
 		os << obj << ' ';
 	return os;
 }
+#endif // UTILS_NO_OSTREAM_OPERATOR_VECTOR
 
+#ifndef UTILS_NO_OSTREAM_OPERATOR_LIST
 #include <list>
 template<typename T>
 std::ostream& operator<<(std::ostream& os, const std::list<T> & objs)
@@ -53,7 +87,7 @@ std::ostream& operator<<(std::ostream& os, const std::list<T> & objs)
 		os << obj << ' ';
 	return os;
 }
-
+#endif // UTILS_NO_OSTREAM_OPERATOR_LIST
 /*
 /// An implementation of operator<< for ostream, (to print std::vector, std::list, etc).
 template<typename T, template<class> class C>
@@ -73,7 +107,7 @@ std::ostream& operator<<(std::ostream& os, const C<T,Args...>& objs)
     return os;
 }//*/
 
-#endif
+#endif // UTILS_NO_OSTREAM_OPERATOR
 
 // Define UTILS_NO_RAND to deactivate the pseudo random number generation (and the inclusion of cstdint).
 #ifndef UTILS_NO_RAND
@@ -113,7 +147,7 @@ int32_t rand_parkmiller(int32_t & seed)     // 1 <= seed < m
 	return seed;
 }
 
-#endif
+#endif // UTILS_NO_RAND
 
 // Define UTILS_NO_CHRONO to deactivate the chronometer.
 #ifndef UTILS_NO_CHRONO
@@ -217,10 +251,10 @@ struct Chronometer
 	}
 };
 
-#else// chronometer
+#else // UTILS_NO_CHRONO defined
 	#define TIMER(str)
 	#define TIMER_FOR(str, N, code) { for(size_t i_TIMER_FOR = 0 ; i_TIMER_FOR < N ; i_TIMER_FOR++) {code} }
-#endif// chronometer
+#endif // UTILS_NO_CHRONO
 
 // Define UTILS_NO_PROFILER to deactivate the profiler.
 #ifndef UTILS_NO_PROFILER