[Boost-commit] svn:boost r74207 - in trunk/libs/chrono: doc example test

Subject: [Boost-commit] svn:boost r74207 - in trunk/libs/chrono: doc example test
From: vicente.botet_at_[hidden]
Date: 2011-09-03 11:44:33

Author: viboes
Date: 2011-09-03 11:44:33 EDT (Sat, 03 Sep 2011)
New Revision: 74207
URL: http://svn.boost.org/trac/boost/changeset/74207

Log:
Chrono: Added rounding utilities
Added:
   trunk/libs/chrono/example/rounding.cpp   (contents, props changed)
Text files modified: 
   trunk/libs/chrono/doc/chrono.qbk  |   134 ++++++++++++++++++++++++++++++++++++++- 
   trunk/libs/chrono/test/Jamfile.v2 |     1                                         
   2 files changed, 130 insertions(+), 5 deletions(-)

Modified: trunk/libs/chrono/doc/chrono.qbk
==============================================================================
--- trunk/libs/chrono/doc/chrono.qbk	(original)
+++ trunk/libs/chrono/doc/chrono.qbk	2011-09-03 11:44:33 EDT (Sat, 03 Sep 2011)
@@ -9,7 +9,7 @@
 
 [library Boost.Chrono
     [quickbook 1.5]
-    [version 1.1.0]
+    [version 1.3.0]
     [authors [Hinnant, Howard]]
     [authors [Dawes, Beman]]
     [authors [Botet Escriba, Vicente J.]]
@@ -243,6 +243,7 @@
 ]
 
 
+
 [endsect]
 
 [/==================]
@@ -278,6 +279,10 @@
 It provides I/O for __duration and __time_point. It builds on `<boost/ratio/ratio_io.hpp>` to provide readable and flexible formatting and parsing for types in `<boost/chrono.hpp>`. The __duration unit names can be customized through a new facet: __duration_punct.
 
 
+[heading Rounding utilities]
+
+A few simple rounding utility functions for working with durations. 
+
 [heading Caveat Emptor]
 
 The underlying clocks provided by operating systems are subject to many seemingly arbitrary policies and implementation irregularities. That's a polite way of saying they tend to be flakey, and each operating system or even each clock has its own cruel and unusual forms of flakiness. Don't bet the farm on their accuracy, unless you have become deeply familiar with exactly what the specific operating system is guaranteeing, which is often very little.
@@ -587,6 +592,66 @@
 
 [endsect]
 
+[section:round Rounding functions]
+
+
+__Boost_Chrono__ provides few simple rounding utility functions for working with durations.
+
+
+    // round down
+    template <class To, class Rep, class Period>
+    To
+    floor(const duration<Rep, Period>& d)
+
+    // round to nearest, to even on tie
+    template <class To, class Rep, class Period>
+    To
+    round(const duration<Rep, Period>& d);
+
+    // round up
+    template <class To, class Rep, class Period>
+    To
+    ceil(const duration<Rep, Period>& d);
+
+
+The beauty of the chrono library is the ease and accuracy with which such conversions can be made. For example to convert from milliseconds (1/1000 of a second), to 1/30 of a second, one must multiply the milliseconds by 0.03. It is common knowledge that you can't exactly represent 0.03 in a computer. Nevertheless round will exactly (with no round off error) detect a tie and round to even when this happens. The differences diff0 and diff1 are not approximate, but exact differences, even when d has the units of millisecond and To is 1/30 of a second. The unit of diff0 and diff1 is 1/3000 of a second which both millisecond and 1/30 of a second exactly convert to (with no truncation error).
+
+Similarly, the comparison t < d in ceil is exact, even when there is no exact conversion between t and d.
+Example use of rounding functions
+
+    #include <iostream>
+    #include <boost/chrono/chrono_io.hpp>
+    #include <boost/chrono/floor.hpp>
+    #include <boost/chrono/round.hpp>
+    #include <boost/chrono/ceil.hpp>
+
+    int main()
+    {
+        using namespace boost::chrono;
+        milliseconds ms(2500);
+        std::cout << floor<seconds>(ms) << '\n';
+        std::cout << round<seconds>(ms) << '\n';
+        std::cout << ceil<seconds>(ms) << '\n';
+        ms = milliseconds(2516);
+        typedef duration<long, boost::ratio<1, 30> > frame_rate;
+        std::cout << floor<frame_rate>(ms) << '\n';
+        std::cout << round<frame_rate>(ms) << '\n';
+        std::cout << ceil<frame_rate>(ms) << '\n';
+
+        return 0;
+    }
+
+The output of this program should be
+
+    2 seconds
+    2 seconds
+    3 seconds
+    75 [1/30]seconds
+    75 [1/30]seconds
+    76 [1/30]seconds
+
+[endsect]
+
 [section Trafficking in floating-point Durations]
 
 I don't want to deal with writing `duration_cast` all over the place. I'm content with the precision of my floating-point representation.
@@ -3174,9 +3239,6 @@
 [/==================================================================]
 
 
-[/The current implementation makes use of a few utilities in libc++ as `__scan_keyword` which has also been ported and seen as implementation details.]
-
-
     namespace boost {
     namespace chrono {
 
@@ -3443,6 +3505,47 @@
 [endsect]
 [endsect]
 
+[section:round Chrono Rounding Utilities]
+[/==================================================================]
+[section:floor_hpp Header `<boost/chrono/floor.hpp>`]
+[/==================================================================]
+
+  namespace boost { namespace chrono {
+    template <class To, class Rep, class Period>
+    To floor(const duration<Rep, Period>& d);
+  } } 
+
+This function round down the given parameter.
+
+[endsect]
+[/==================================================================]
+[section:round_hpp Header `<boost/chrono/round.hpp>`]
+[/==================================================================]
+
+  namespace boost { namespace chrono {
+    template <class To, class Rep, class Period>
+    To round(const duration<Rep, Period>& d);
+  } } 
+
+This function round to nearest, to even on tie the given parameter.
+
+
+[endsect]
+[/==================================================================]
+[section:ceil_hpp Header `<boost/chrono/ceil.hpp>`]
+[/==================================================================]
+
+  namespace boost { namespace chrono {
+    template <class To, class Rep, class Period>
+    To ceil(const duration<Rep, Period>& d);
+  } } 
+
+This function round up the given parameter.
+
+[endsect]
+[endsect]
+
+
 [section:other_clocks Other Clocks]
 
 [/==================================================================]
@@ -3934,6 +4037,25 @@
 [section:history Appendix A: History]
 [/==================================]
 
+[section [*Version 1.3.0, September 3, 2011] ]
+
+[*New Features:]
+* Added chrono utilities as defined By Howard Hinnant [@http://home.roadrunner.com/~hinnant/duration_io/chrono_util.html here].
+
+[*Fixes:]
+
+[endsect] [/section [*Version 1.3.0, September 3, 2011] ]
+
+[section [*Version 1.2.0, September 3, 2011] ]
+
+[*Fixes:]
+
+* [@http://svn.boost.org/trac/boost/ticket/5669 #5669] Intel compiler failure to compile duration.hpp
+* [@http://svn.boost.org/trac/boost/ticket/2114 #2114] Enable visibility support (Boost.Chorno part)
+
+[endsect] [/section [*Version 1.2.0, September 3, 2011] ]
+
+
 [section [*Version 1.1.0, Mars 17, 2011] ]
 
 [*New Features:]
@@ -4641,8 +4763,10 @@
 
 [heading For later releases]
 
-* Add chrono utilities as defined By Howard Hinnant [@http://home.roadrunner.com/~hinnant/duration_io/chrono_util.html here].
+* Enhance chrono I/O to take care of the Howard Hinnant [@http://home.roadrunner.com/~hinnant/bloomington/chrono_io.html proposal] which has the advantage to provide I/O for system clocks using the Gregorian Calendar.
 
+* Include chrono::date as defined by Howard Hinnant [@http://home.roadrunner.com/~hinnant/bloomington/date.html here].
+  
 [endsect]
 
 [endsect]

Added: trunk/libs/chrono/example/rounding.cpp
==============================================================================
--- (empty file)
+++ trunk/libs/chrono/example/rounding.cpp	2011-09-03 11:44:33 EDT (Sat, 03 Sep 2011)
@@ -0,0 +1,30 @@
+//  french.cpp  ----------------------------------------------------------//
+
+//  Copyright 2010 Howard Hinnant
+//  Copyright 2011 Vicente J. Botet Escriba
+//  Distributed under the Boost Software License, Version 1.0.
+//  See http://www.boost.org/LICENSE_1_0.txt
+
+// Adapted to Boost from the original Hawards's code
+
+#include <iostream>
+#include <boost/chrono/chrono_io.hpp>
+#include <boost/chrono/floor.hpp>
+#include <boost/chrono/round.hpp>
+#include <boost/chrono/ceil.hpp>
+
+int main()
+{
+        using namespace boost::chrono;
+        milliseconds ms(2500);
+        std::cout << floor<seconds>(ms) << '\n';
+        std::cout << round<seconds>(ms) << '\n';
+        std::cout << ceil<seconds>(ms) << '\n';
+        ms = milliseconds(2516);
+        typedef duration<long, boost::ratio<1, 30> > frame_rate;
+        std::cout << floor<frame_rate>(ms) << '\n';
+        std::cout << round<frame_rate>(ms) << '\n';
+        std::cout << ceil<frame_rate>(ms) << '\n';
+
+        return 0;
+}

Modified: trunk/libs/chrono/test/Jamfile.v2
==============================================================================
--- trunk/libs/chrono/test/Jamfile.v2	(original)
+++ trunk/libs/chrono/test/Jamfile.v2	2011-09-03 11:44:33 EDT (Sat, 03 Sep 2011)
@@ -181,6 +181,7 @@
         [ chrono-run ../example/chrono_accuracy_test.cpp ]
         [ chrono-run-mt ../example/test_thread_clock.cpp  ]
         [ chrono-run ../example/french.cpp  ]
+        [ chrono-run ../example/rounding.cpp  ]
         #[ chrono-run ../example/await_keystroke.cpp  ]
         ;