From 1b8fabe9231b2acd0a0faadf4a82a0bd4f35f684 Mon Sep 17 00:00:00 2001
From: Roland Conybeare <rconybeare@gmail.com>
Date: Sat, 4 May 2024 12:00:31 -0400
Subject: [PATCH] xo-unit: doc/example streamlining

---
 docs/examples.rst   | 55 ++++++++++++++++++++++++++++-----------------
 example/ex4/ex4.cpp |  5 +++--
 2 files changed, 37 insertions(+), 23 deletions(-)

diff --git a/docs/examples.rst b/docs/examples.rst
index 0360f0a..0787602 100644
--- a/docs/examples.rst
+++ b/docs/examples.rst
@@ -144,7 +144,7 @@ See ``xo-unit/example/ex3`` for code below
 
 .. code-block:: cpp
    :linenos:
-   :emphasize-lines: 11-12
+   :emphasize-lines: 12-13
 
     int
     main () {
@@ -173,12 +173,12 @@ with output:
 
 Remarks:
 
-*  Assignment to ``t`` converted to representation ``double``.
-   We could have used :code:`quantity<nu::second, int>` to preserve
-   right-hand-side representation.
+- Assignment to ``t`` converted to representation ``double``.
+  We could have used :code:`quantity<nu::second, int>` to preserve
+  right-hand-side representation.
 
-Scale conversion triggered by arithmetic
-----------------------------------------
+Scale conversion and arithmetic
+-------------------------------
 
 When representing a particular quantity,
 xo-unit uses at most one scale for each :term:`basis dimension` associated with the unit for that quantity.
@@ -210,37 +210,50 @@ with output:
 
     t1: 1ms, t2: 1min, t1*t2: 60000ms^2
 
-Dimensionless quantities collapse automatically
------------------------------------------------
+Dimensionless quantities unwrap implicitly
+------------------------------------------
+
+See ``xo-unit/examples/ex4`` for code below.
 
 .. code-block:: cpp
    :linenos:
-   :emphasize-lines: 14-15
+   :emphasize-lines: 23,26
 
     #include "xo/unit/quantity.hpp"
+    #include "xo/unit/quantity_iostream.hpp"
     #include <iostream>
 
-    int main() {
-        namespace u = xo::unit;
-        namespace qty = xo::units::qty;
-        using namespace std;
+    int
+    main () {
+        namespace q = xo::qty::qty;
 
-        auto t1 = qty::milliseconds(1);
-        auto t2 = qty::minutes(1);
-        auto r1 = t1 / t2.with_repr<double>();
-        auto r2 = t2 / t1.with_repr<double>();
+        auto t1 = q::milliseconds(1);
+        auto t2 = q::minutes(1);
+
+        auto r1 = t1 / with_repr<double>(t2);
+
+        static_assert(r1.is_dimensionless());
+        static_assert(!t2.is_dimensionless());
+
+        static_assert(std::same_as<static_cast<double>(r1), double>);
+
+        // static_assert fails b/c static_cast only available for dimensionless quantity
+        //static_assert(std::same_as<decltype(static_cast<double>(t2)), double>);
+
+        // r1_value: assignment compiles,  since r1 dimensionless
+        double r1_value = r1;
 
-        static_assert<same_as<decltype(r1), double>);
-        static_assert<same_as<decltype(r2), double>);
+        // r2_value: assignment won't compile,  'cannot convert' error
+        //double r2_value = t2;
 
-        cerr << "t1: " << t1 << ", t2: " << t2 << ", t1/t2: " << r1 << ", t2/t1: " << r2 << endl;
+        std::cerr << "t1: " << t1 << ", t2: " << t2 << ", t1/t2: " << r1_value << std::endl;
     }
 
 with output:
 
 .. code-block::
 
-    t1: 1ms, t2: 1min, t1/t2: 1.66667e-05, t2/t1: 60000
+    t1: 1ms, t2: 1min, t1/t2: 1.66667e-05
 
 
 Fractional dimension
diff --git a/example/ex4/ex4.cpp b/example/ex4/ex4.cpp
index 7714b48..573a6b9 100644
--- a/example/ex4/ex4.cpp
+++ b/example/ex4/ex4.cpp
@@ -6,9 +6,7 @@
 
 int
 main () {
-    //namespace u = xo::qty::units;
     namespace q = xo::qty::qty;
-    using xo::qty::with_repr;
 
     auto t1 = q::milliseconds(1);
     auto t2 = q::minutes(1);
@@ -18,6 +16,9 @@ main () {
     static_assert(r1.is_dimensionless());
     static_assert(!t2.is_dimensionless());
 
+    static_assert(std::same_as<decltype(static_cast<double>(r1)), double>);
+    //static_assert(std::same_as<decltype(static_cast<double>(t2)), double>);
+
     /* r1_value: assignment compiles,  since r1 dimensionless */
     double r1_value = r1;