refactor: References are now guarded UNITS_REFERENCES with (ON by default) + examples duplicated to subdirectories

Now References can be disabled to meassure a compile time impact. Also the same examples are now provided in two subdirectories to be able to easily compare the pros and cons of every quantity construction technique.

docs/Doxyfile.in

@@ -91,3 +91,14 @@ WARN_AS_ERROR          = NO
 # The default value is: NO.
 
 QUIET                  = YES
+
+# The PREDEFINED tag can be used to specify one or more macro names that are
+# defined before the preprocessor is started (similar to the -D option of e.g.
+# gcc). The argument of the tag is a list of macros of the form: name or
+# name=definition (no spaces). If the definition and the "=" are omitted, "=1"
+# is assumed. To prevent a macro definition from being undefined via #undef or
+# recursively expanded use the := operator instead of the = operator.
+# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
+
+PREDEFINED             = UNITS_REFERENCES \
+                         UNITS_LITERALS

docs/examples/avg_speed.rst

@@ -1,7 +1,7 @@
 avg_speed
 =========
 
-.. literalinclude:: ../../example/avg_speed.cpp
+.. literalinclude:: ../../example/references/avg_speed.cpp
   :caption: avg_speed.cpp
   :start-at: #include
   :linenos:

docs/examples/box_example.rst

@@ -1,7 +1,7 @@
 box_example
 ===========
 
-.. literalinclude:: ../../example/box_example.cpp
+.. literalinclude:: ../../example/references/box_example.cpp
   :caption: box_example.cpp
   :start-at: #include
   :linenos:

docs/examples/capacitor_time_curve.rst

@@ -1,7 +1,7 @@
 capacitor_time_curve
 ====================
 
-.. literalinclude:: ../../example/capacitor_time_curve.cpp
+.. literalinclude:: ../../example/references/capacitor_time_curve.cpp
   :caption: capacitor_time_curve.cpp
   :start-at: #include
   :linenos:

docs/examples/clcpp_response.rst

@@ -1,7 +1,7 @@
 clcpp_response
 ==============
 
-.. literalinclude:: ../../example/clcpp_response.cpp
+.. literalinclude:: ../../example/references/clcpp_response.cpp
   :caption: clcpp_response.cpp
   :start-at: #include
   :linenos:

docs/examples/conversion_factor.rst

@@ -1,7 +1,7 @@
 conversion_factor
 =================
 
-.. literalinclude:: ../../example/conversion_factor.cpp
+.. literalinclude:: ../../example/references/conversion_factor.cpp
   :caption: conversion_factor.cpp
   :start-at: #include
   :linenos:

docs/examples/custom_systems.rst

@@ -1,7 +1,7 @@
 custom_systems
 ==============
 
-.. literalinclude:: ../../example/custom_systems.cpp
+.. literalinclude:: ../../example/references/custom_systems.cpp
   :caption: custom_systems.cpp
   :start-at: #include
   :linenos:

docs/examples/foot_pound_second.rst

@@ -1,7 +1,7 @@
 foot_pound_second
 =================
 
-.. literalinclude:: ../../example/foot_pound_second.cpp
+.. literalinclude:: ../../example/references/foot_pound_second.cpp
   :caption: foot_pound_second.cpp
   :start-at: #include
   :linenos:

docs/examples/glide_computer.rst

@@ -13,7 +13,7 @@ This example presents the usage of:
 - quantities text output formatting,
 - cooperation with `std::chrono`.
 
-.. literalinclude:: ../../example/glide_computer.h
+.. literalinclude:: ../../example/references/glide_computer.h
   :caption: glide_computer.h
   :start-at: #include
   :end-before: using namespace units;
@@ -35,7 +35,7 @@ For example we have 3 for a quantity of length:
 - ``height`` - a relative altitude difference between 2 points in the air
 - ``altitude`` - an absolute altitude value measured form the mean sea level (AMSL).
 
-.. literalinclude:: ../../example/glide_computer.h
+.. literalinclude:: ../../example/references/glide_computer.h
   :caption: glide_computer.h
   :start-at: using namespace units;
   :end-before: // text output
@@ -44,7 +44,7 @@ For example we have 3 for a quantity of length:
 
 Next a custom text output is provided both for C++ output streams and the text formatting facility.
 
-.. literalinclude:: ../../example/glide_computer.h
+.. literalinclude:: ../../example/references/glide_computer.h
   :caption: glide_computer.h
   :start-at: // text output
   :end-before: // definition of glide computer databases and utilities
@@ -58,13 +58,13 @@ convert it to the one required by the engine interface.
 The glide calculator takes task created as a list of waypoints, glider performance data, weather conditions,
 safety constraints, and a towing height.
 
-.. literalinclude:: ../../example/glide_computer.h
+.. literalinclude:: ../../example/references/glide_computer.h
   :caption: glide_computer.h
   :start-at: // definition of glide computer databases and utilities
   :linenos:
   :lineno-match:
 
-.. literalinclude:: ../../example/glide_computer_example.cpp
+.. literalinclude:: ../../example/references/glide_computer_example.cpp
   :caption: glide_computer_example.cpp
   :start-at: #include
   :linenos:
@@ -74,7 +74,7 @@ Having all of that it estimates the number of flight phases (towing, circling, g
 needed to finish a task. As an output it provides the duration needed to finish the task while
 flying a selected glider in the specific weather conditions.
 
-.. literalinclude:: ../../example/glide_computer.cpp
+.. literalinclude:: ../../example/references/glide_computer.cpp
   :caption: glide_computer.cpp
   :start-at: #include
   :linenos:

docs/examples/kalman_filter-alpha_beta_filter_example2.rst

@@ -4,7 +4,7 @@ kalman_filter-alpha_beta_filter_example2
 This example is based on the 1d aircraft α-β filter example 2 from the
 `Kalman Filter <https://www.kalmanfilter.net/alphabeta.html#ex2>`_ tutorial.
 
-.. literalinclude:: ../../example/kalman_filter-alpha_beta_filter_example2.cpp
+.. literalinclude:: ../../example/references/kalman_filter-alpha_beta_filter_example2.cpp
   :caption: kalman_filter-alpha_beta_filter_example2.cpp
   :start-at: #include
   :linenos:

docs/examples/linear_algebra.rst

@@ -1,7 +1,7 @@
 linear_algebra
 ==============
 
-.. literalinclude:: ../../example/linear_algebra.cpp
+.. literalinclude:: ../../example/references/linear_algebra.cpp
   :caption: linear_algebra.cpp
   :start-at: #include
   :linenos:

docs/examples/measurement.rst

@@ -1,7 +1,7 @@
 measurement
 ===========
 
-.. literalinclude:: ../../example/measurement.cpp
+.. literalinclude:: ../../example/references/measurement.cpp
   :caption: measurement.cpp
   :start-at: #include
   :linenos:

docs/examples/total_energy.rst

@@ -1,7 +1,7 @@
 total_energy
 ============
 
-.. literalinclude:: ../../example/total_energy.cpp
+.. literalinclude:: ../../example/references/total_energy.cpp
   :caption: total_energy.cpp
   :start-at: #include
   :linenos:

docs/examples/unknown_dimension.rst

@@ -1,7 +1,7 @@
 unknown_dimension
 =================
 
-.. literalinclude:: ../../example/unknown_dimension.cpp
+.. literalinclude:: ../../example/references/unknown_dimension.cpp
   :caption: unknown_dimension.cpp
   :start-at: #include
   :linenos:

docs/framework/quantities.rst

@@ -56,6 +56,8 @@ Quantity References
 Quantity References provide an alternative and simplified way to create quantities.
 They are defined using the `reference` class template::
 
+    #ifdef UNITS_REFERENCES
+
     namespace references {
 
     inline constexpr auto km = reference<dim_length, kilometre>{};
@@ -63,6 +65,8 @@ They are defined using the `reference` class template::
 
     }
 
+    #endif // UNITS_REFERENCES
+
 With the above our code can look as follows::
 
     using namespace units::isq::si::references;
@@ -103,8 +107,6 @@ Alternatively, to construct quantities with compile-time known values the librar
 
 Thanks to them the same code can be as simple as::
 
-    #define UNITS_LITERALS
-
     using namespace units::isq::si::literals;
     auto d = 123._q_km;     // si::length<si::kilometre, long double>
     auto v = 70_q_km_per_h; // si::speed<si::kilometre_per_hour, std::int64_t>
@@ -122,7 +124,7 @@ Thanks to them the same code can be as simple as::
 
     As one can read in the next section UDLs, are considered to be inferior to `Quantity References`_
     and their definition affects compile-time performance a lot. This is why they are an opt-in feature
-    of the library and in order to use them one has to provide a `UNITS_UDL` preprocessor definition.
+    of the library and in order to use them one has to provide a `UNITS_LITERALS` preprocessor definition.
 
     
 UDLs vs Quantity References

docs/quick_start.rst

@@ -40,8 +40,6 @@ but still easy to use interface where all unit conversions and dimensional analy
 performed without sacrificing on accuracy. Please see the below example for a quick preview
 of basic library features::
 
-    #define UNITS_LITERALS
-
     #include <units/format.h>
     #include <units/isq/si/length.h>
     #include <units/isq/si/speed.h>

docs/usage.rst

@@ -123,6 +123,15 @@ It also runs unit tests during Conan build.
 Conan Options
 ^^^^^^^^^^^^^
 
+references
+++++++++++
+
+**Values**: ``True``/``False``
+
+**Defaulted to**: ``True``
+
+Determines if library should provide Quantity References for quantities of various units.
+
 literals
 ++++++++
 
@@ -158,6 +167,16 @@ Additionally, enables project documentation generation when the project is being
 CMake Options
 ^^^^^^^^^^^^^
 
+UNITS_REFERENCES
+++++++++++++++++
+
+**Values**: ``ON``/``OFF``
+
+**Defaulted to**: ``ON``
+
+Equivalent to `references`_.
+
+
 UNITS_LITERALS
 ++++++++++++++