From 5292b19dd6fe9d22d5e6a12513e9f8b7d18fcdef Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Sun, 2 Dec 2012 01:54:02 +0100 Subject: [PATCH] clean-up and finalise time::Mutation --- src/lib/time/mutation.cpp | 47 ++++++++++++++++++--------- src/lib/time/mutation.hpp | 23 ++++++++----- tests/lib/time/time-mutation-test.cpp | 5 +-- 3 files changed, 47 insertions(+), 28 deletions(-) diff --git a/src/lib/time/mutation.cpp b/src/lib/time/mutation.cpp index da018fb0c..204869bc4 100644 --- a/src/lib/time/mutation.cpp +++ b/src/lib/time/mutation.cpp @@ -21,21 +21,37 @@ * *****************************************************/ +/** @file mutation.cpp + ** A collection of concrete forms of time mutation. + ** This compilation unit defines some "mutators" based on explicitly given time values, + ** to be applied to time durations, time spans and quantised time values. The intended + ** usage is to build these "mutators" inline through use of the corresponding static + ** builder functions defined in class Mutation. All the mutators defined here are + ** "polymorphic value objects", i.e. they can be treated like simple time values, while + ** actually hiding the concrete implementation and just exposing the #Mutation interface. + ** + ** @remarks these mutators are for casual use at places where you'd intuitively just want + ** set a simple more or less hard wired value. The benefit of this seemingly complicated + ** solution is that all the tricky corner cases for grid aligned time values will be + ** treated automatically. Incidentally, there is another, quite different use case + ** for time mutations, when it comes to receive continuous and ongoing changes to + ** a time value (e.g. a cursor). This separate use case is handled by time::Control + ** + ** @see time::Control + ** @see lib::PolymorphicValue + ** @see TimeMutation_test + ** @see TimeControl_test + ** + */ + + #include "lib/error.hpp" #include "lib/time/timevalue.hpp" #include "lib/time/timequant.hpp" #include "lib/time/timecode.hpp" #include "lib/time/mutation.hpp" -//#include "lib/time.h" #include "lib/util-quant.hpp" -#include "lib/util.hpp" -//#include - -//using std::string; -//using util::unConst; -//using util::floorwrap; -using util::isnil; namespace error = lumiera::error; @@ -52,8 +68,9 @@ namespace time { + /* Warning: all the classes defined here must be of size below MUTATION_IMPL_SIZE */ - /** + /** * concrete time value mutation: * impose fixed new start time. */ @@ -94,7 +111,7 @@ namespace time { }; - /** + /** * concrete time value mutation: * set a new overall duration for an extended timespan. */ @@ -135,7 +152,7 @@ namespace time { }; - /** + /** * concrete time value mutation: * adjust the given time entity by an offset amount. */ @@ -175,7 +192,7 @@ namespace time { }; - /** + /** * concrete time value mutation: * make the grid aligned time value explicit, * and impose the resulting value to the given @@ -192,7 +209,7 @@ namespace time { }; - /** + /** * concrete time value mutation: * nudge target value by the given number of 'steps', * relative to the given grid. @@ -215,7 +232,7 @@ namespace time { }; - /** + /** * concrete time value mutation: * nudge based on a implicit grid, which is * either a quantised target value's own grid, @@ -360,4 +377,4 @@ namespace time { }} // lib::time - + diff --git a/src/lib/time/mutation.hpp b/src/lib/time/mutation.hpp index 4fd277bff..297bdda9d 100644 --- a/src/lib/time/mutation.hpp +++ b/src/lib/time/mutation.hpp @@ -46,8 +46,16 @@ ** between multiple time grids may be happen, possibly resulting in a re-quantisation of ** the message into the target object's own time grid. ** - ** @todo WIP-WIP-WIP - ** + ** @note this header is defined such as to be used with or without including the time quantisation + ** facility, which is a more heavyweight regarding code size and compilation times. For this + ** toggle to work, the header \c timequant.hpp needs to be included \em prior to \c mutation.hpp + ** Obviously, you can't define any mutation involving quantised (grid aligned) values without this. + ** @warning when defining more fancy kinds of concrete mutations using the technique with + ** the EncapsulatedMutation to hide the implementation, then please be sure to understand + ** the size limitation for the implementation and maybe adjust MUTATION_IMPL_SIZE accordingly. + ** @see TimeMutation_test + ** @see TimeControl_test + ** */ #ifndef LIB_TIME_MUTATION_H @@ -59,17 +67,12 @@ #include "lib/symbol.hpp" #include -//#include -//#include -//#include namespace lib { namespace time { using lib::Symbol; -//using std::string; -//using lib::Literal; LUMIERA_ERROR_DECLARE (INVALID_MUTATION); ///< Changing a time value in this way was not designated @@ -91,7 +94,8 @@ namespace time { * Interface: an opaque change imposed onto some time value. * * @see time::TimeSpan#accept(Mutation const&) - * @todo WIP-WIP-WIP + * @see TimeMutation_test + * @see polymorphic-value.hpp */ class Mutation { @@ -123,7 +127,7 @@ namespace time { /* === defining the visitation responses === */ - + inline void Duration::accept (Mutation const& muta) { muta.change (*this); } inline void TimeSpan::accept (Mutation const& muta) { muta.change (*this); } @@ -180,5 +184,6 @@ namespace time { #endif + }} // lib::time #endif diff --git a/tests/lib/time/time-mutation-test.cpp b/tests/lib/time/time-mutation-test.cpp index 2a4837fcb..32730824f 100644 --- a/tests/lib/time/time-mutation-test.cpp +++ b/tests/lib/time/time-mutation-test.cpp @@ -1,5 +1,5 @@ /* - TimeMutation(Test) - explicitly changing time spcifications + TimeMutation(Test) - explicitly changing time specifications Copyright (C) Lumiera.org 2011, Hermann Vosseler @@ -30,13 +30,10 @@ #include "lib/util.hpp" #include -#include #include using boost::lexical_cast; using util::isnil; -using std::cout; -using std::endl; using std::string;