A PlotExpression represents an operation in a plot equation. More...

#include <plotexpression.h>

Inheritance diagram for PlotExpression:

Public Member Functions
	PlotExpression ()
	Empty constructor.

virtual	~PlotExpression ()
	Empty, virtual destructor.

virtual double	sample (double sampleTime) const =0
	Called to generate a sample at `sampleTime`. More...

virtual BindResult	bind (const QList< PlotInstance * > &curves, PlotBindingTracker &bindTracker, PlotExpressionBindDomain &domain, bool repeatLastBinding=false)=0
	Attempts to binds the `PlotExpression` to sample the given `curves`. More...

virtual void	unbind ()
	Unbinds the sampling state once sampling has completed. More...

virtual PlotExpression *	clone () const =0
	Performs a deep clone of the `PlotExpression`. More...

QString	toString () const
	Converts the `PlotExpression` into a parseable string form. More...

virtual bool	explicitTime () const
	Is the curve generated with explicit time values? More...

Detailed Description

A PlotExpression represents an operation in a plot equation.

Derivations implement specific operations such as sampling a curve, summing two curve, etc.

A PlotExpression may represent a single operation, or it may combine multiple expressions, forming an expression tree. New plots are generated based on existing curves using a PlotExpression root expression.

Each expression is given the change to generate new curves by the following sequence of operations:

For each curve source file:
- Invoke bind() to validate expression generation for this source file.
- Generate a new curve for each successfull bind()
- Iterate the sample range generated by the PlotExpressionBindInfo from bind()
  - Call sample() for each time value.
- Cleanup by calling unbind()
- Attempt next binding

A successfull call to bind() defines the sample range and sample step for the generated curve, as defined by PlotExpressionBindInfo. This allows calls to sample() until unbind() is called.

Note that an expression may be able to bind to multiple curves in the group passed to bind(). For example, given the set of curves [ X_1, X_3, X_4, Y_1, Y_2 ], the regular expression r'X_[0-9]' matches the first three curves. Implementations of the bind() are free to match only the first item, however, in some cases such as the regular expression example, it is desirable to bind and generate each viable curve in turn.

The bind() method supports repeated bindings via a MultiBindingTracker object. A bind() implementation may optionally set a single marker value to the MultiBindingTracker and return BoundMaybeMore. The return value preempts a repeated call to bind() during which the expression may check the existing marker value and resume binding with a new curve. The simplest way to manage the marker value is to use it as the index of the last successfully bound curve.

Some expression trees may support multiple bindings on different parts of the tree. Consider the following expression: r'X_[0-9]' + r'Y_[0-9]'. An exhaustive binding on the curve set defined above should result in six bindings, as all X_ and Y_ curves are summed against each other. Each PlotExpression can maintain its own marker, but a marker must be removed once the associated binding fails, or cannot yield further success. That is, the Y marker must be remove once Y_2 is bound as this is the last viable match of the Y expression. At the same time, the X marker must be held to a constant value so long as new Y values are successfully bound. MultiBindingTracker also tracks a hold status for an expression, implying it should return bind the same result as the last successful binding.

A viable binding sequence for the example above may be:

Bind X_1, set X marker to 0 (index of X_1).
Bind Y_1, set Y marker to 3 (index of Y_1).
Complete expression binding.
Hold X_1 binding, bind Y_2, clear Y marker
Complete expression binding.
Bind X_3, set X marker to 1.
Bind Y_1, set Y marker to 3 (index of Y_1).
...
Bind X_4, set X marker to 2.
...
Hold X_4 binding, bind Y_2, clear Y marker.
Complete expression binding.
Attempt to bind new X, failing to do so, clear X marker.

Derivations must implement the following methods:

sample() - Generate a sample at the requested time.
bind() - Initialise sampling of the expression on the given operands.
unbind() - (Optional) Clean up sampling state.
clone() - Create a deep clone of the PlotExpression.
stringExpression() - Reverse engineer the PlotExpression back to a parseable string form.

Member Function Documentation

virtual BindResult PlotExpression::bind	(	const QList< PlotInstance * > &	curves,
		PlotBindingTracker &	bindTracker,
		PlotExpressionBindDomain &	domain,
		bool	repeatLastBinding = `false`
	)

pure virtual

Attempts to binds the PlotExpression to sample the given curves.

The bind() implementations must first check if the PlotExpression can be evaluated for the given set of PlotInstance curve objects. For example, this may involve checking if a curve matching of a particular name exists. If all requirements are met, then implementation must prepare for sampling by:

Storing relevant PlotInstance curve objects for sampling.
Define the sampling domain in info.

Calls to bind() are expected to be followed by sample() calls ending with a call to unbind().

Parameters

	curves	The set of existing curves available for sampling. These are the curves which were loaded from the source named `sourceFile`.
	bindTracker	Tracks the last binding on a per expression basis.
[out]	domain	To be populated with bound domain details if a successful binding can be made.
	repeatLastBinding	True to request that the function rebind whatever it bound last time it was called, according to the `bindTracker`. Bind the first possibility if there is no such last binding.

Returns: True if binding is successful, info is valid and sampling can occur. False if the expression cannot be resolved in the context of the given curves.

Implemented in PlotSample, PlotSlice, PlotBinaryOperator, PlotFunction, PlotUnaryOperator, and PlotConstant.

virtual PlotExpression* PlotExpression::clone ( ) const

pure virtual

Performs a deep clone of the PlotExpression.

Returns: A clone of the expression.

Implemented in PlotSample, PlotBinaryOperatorT< Operator >, PlotBinaryOperatorT< Power< double > >, PlotBinaryOperatorT< std::multiplies< double > >, PlotBinaryOperatorT< std::plus< double > >, PlotBinaryOperatorT< std::divides< double > >, PlotBinaryOperatorT< std::minus< double > >, PlotSlice, PlotUnaryOperatorT< Operator >, PlotUnaryOperatorT< std::negate< double > >, PlotFunction, PlotConstant, PlotIndexExpression, and PlotBracketExpression.

Referenced by PlotUnaryOperatorT< std::negate< double > >::clone(), and PlotBinaryOperatorT< std::minus< double > >::clone().

virtual bool PlotExpression::explicitTime ( ) const

inlinevirtual

Is the curve generated with explicit time values?

Some expressions, such as slicing, are dependent on explicit time values and may require regeneration if the time scale, time base or time column are changed. Such expressions should return true from this method. Tree expressions should return true if any child expression returns true.