From bbf7a18b667b913c00a46a99a68e33d26aa69800 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=B4me?= Date: Thu, 2 May 2019 08:58:21 +0200 Subject: [PATCH] Added file documentation explaining and listing the features. --- utils.hpp | 44 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/utils.hpp b/utils.hpp index 0ac7b8a..73bbe90 100644 --- a/utils.hpp +++ b/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 & objs)` to print the contents of an std::vector to an ostream. +/// - `operator<<(std::ostream& os, const std::list & 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 . +/// - UTILS_NO_CHRONO : Deactivates the `Chronometer` class. Removes the inclusion of the following standard headers : . +/// - UTILS_NO_PROFILER : Deactivates the `Profiler` class. Removes the inclusion of the following standard headers : . +/// - 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 #include @@ -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 template std::ostream& operator<<(std::ostream& os, const std::vector & objs) @@ -44,7 +76,9 @@ std::ostream& operator<<(std::ostream& os, const std::vector & objs) os << obj << ' '; return os; } +#endif // UTILS_NO_OSTREAM_OPERATOR_VECTOR +#ifndef UTILS_NO_OSTREAM_OPERATOR_LIST #include template std::ostream& operator<<(std::ostream& os, const std::list & objs) @@ -53,7 +87,7 @@ std::ostream& operator<<(std::ostream& os, const std::list & 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 class C> @@ -73,7 +107,7 @@ std::ostream& operator<<(std::ostream& os, const C& 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