eu.bandm.music.entities

Class MetricConsumer

java.lang.Object

eu.bandm.music.entities.MetricConsumer

public class MetricConsumer
extends Object

Consumes a prefix of a list of QualifiedRational by using a MSplitter, returns its result and additionally information about the rest sequence. The MSplitter can change with every analysis step, i.e. after the prefix corresponding to one complete measure has been acceped. This can realize changes in the metrum of a score.
Usage in detail:

• create an instance by calling "byStartPoints(..)" or "byDurations(..)".
• call changeMetrum(MSplitter) to set the metrum.
• call hasNext() or hasCompleteNext(), to find out whether there is some input left to consume, or even enough for at least 1 complete measure
• call getNext() to execute the splitting. This is done by employing the currently selected MSplitter. All further calls to inquiry functions reflect the "current measure", which is the result of the last call to getNext().
• afterwards the result is presented by getResult(): the MSplitter.Result object from the last call to getNext().
• but better to create a MetricConsumer.WriteOut instance, override the call-back methods and call its MetricConsumer.WriteOut.process(). The signatures are the same as with MSplitter.Result.WriteOut, but only here the index value and the boolean flags reflect the "cross-measure-bar" situation.
• there is more resulting information about the current measure delivered by getResultIndex(), getMeasureStart(), firstIsOverlap(), getLastOverlap(), isIncomplete(), getNextIndex(), getNextMeasureStart().

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	MetricConsumer.WriteOut Basic class for writing out the result of the last getNext() call.

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	firstIsOverlap Whether the first event in the current measure is overlapping from the preceding measure.
protected List<QualifiedRational>	input The list of input data, either strictly ascending time points of duration values.
protected int	inputsize The number of time points in input.
protected boolean	isIncomplete Whether the input data is exhausted and could not fill the currently recognized measure completely.
protected Rational	lastOverlapDuration If !=0/1, this is the part of the last processed event (=nextIndex), which overlaps into the next measure.
protected QualifiedRational	lastQRinMeasure The nominally last time point in a measure, relative to the measure.
protected Rational	lastTp The last time point data in the input = the end time point of the last event.
protected Rational	measureLength The currently valid duration of a measure, defined by the metric tree spec underlying the current metricSplitter.
protected Rational	measureStart Running cursor of the time of the measure start relative to the input data.
protected MSplitter	metricSplitter The currently valid MetricSplitter, representing the currently valid metrum.
protected MSplitter.Result	metricSplitterResult The result of the last call to metric split, reflects the analysis of the accepted prefix of the input data.
protected int	nextIndex Index of the next event to process on the next call to getNext().
protected Rational	nextMeasureStart The start time point of the next measure, calculated by adding its length to the start of the last accepted measure.
protected int	resultIndex Index of the input time point which corresponds to the start point of the first event in the recognized prefix / measure.
protected boolean	tailDiscarded Local flag that any synthetic very last event shall not be processed by the write out visitor.

Method Summary

Modifier and Type	Method and Description
static MetricConsumer	byDurations(@Opt MSplitter metricSplitter, List<QualifiedRational> input) Factory method for a user.
static MetricConsumer	byDurations(@Opt MSplitter metricSplitter, List<Rational> input, boolean soundNotPause) Factory method for a user.
static MetricConsumer	byStartPoints(@Opt MSplitter metricSplitter, List<QualifiedRational> input)
static MetricConsumer	byStartPoints(@Opt MSplitter metricSplitter, List<Rational> input, boolean soundNotPause) Factory method for a user.
void	changeMetrum(MSplitter newms) Change the metric splitter and thus the meter to be used for the next splitting operations.
void	discardSyntheticTail() Discard the last event, which was only synthesized for completing the measure.
boolean	firstIsOverlap() Whether the first node in the current result (=event getResultIndex) is an overlap from the last measure.
Rational	getLastOverlap() The length of the part of the last event of the current result which will overlap into the next measure.
Rational	getMeasureStart() Get the start of the current getResult measure.
void	getNext() This method performs the metric analysis of a prefix of the input data, according to the currently selected metrum (see changeMetrum(MSplitter) and consumes as much as possible to fill one complete measure.
int	getNextIndex() The index of the event which will be the first in the NEXT measure, i.e.
Rational	getNextMeasureStart() Get the end point the current getResult measure, ie.
Rational	getRestDuration() The total of all events which have not yet been consumed.
MSplitter.Result	getResult() Returns the result of the last getNext() call to the metric splitter; for details see MetricSplitter.Result.
int	getResultIndex() The index of the first event in the current result measure, may be a trailing overlap from the last event in the preceding measure.
boolean	hasCompleteNext() Whether there are unconsumed events, or at least one partially unconsumed event, which fill at least one complete measure, according to the currently set Metrum.
boolean	hasNext() Whether there are unconsumed events, or at least one partially unconsumed event.
boolean	isIncomplete() Whether the current measure is the very last, and its last event has been synthesized to fill it up.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

metricSplitter

protected MSplitter metricSplitter

The currently valid MetricSplitter, representing the currently valid metrum.

measureLength

protected Rational measureLength

The currently valid duration of a measure, defined by the metric tree spec underlying the current metricSplitter.

lastQRinMeasure

protected QualifiedRational lastQRinMeasure

The nominally last time point in a measure, relative to the measure. This is identical with the measure's duration. Set in the constructor For convenience only.

input

protected final List<QualifiedRational> input

The list of input data, either strictly ascending time points of duration values.

inputsize

protected final int inputsize

The number of time points in input. One large than the number of events. Set in the constructor For convenience only.

lastTp

protected final Rational lastTp

The last time point data in the input = the end time point of the last event. Set in the constructor For convenience only.

metricSplitterResult

@Opt
protected MSplitter.Result metricSplitterResult

The result of the last call to metric split, reflects the analysis of the accepted prefix of the input data.

resultIndex

protected int resultIndex

Index of the input time point which corresponds to the start point of the first event in the recognized prefix / measure.

measureStart

protected Rational measureStart

Running cursor of the time of the measure start relative to the input data.

firstIsOverlap

protected boolean firstIsOverlap

Whether the first event in the current measure is overlapping from the preceding measure.

lastOverlapDuration

protected Rational lastOverlapDuration

If !=0/1, this is the part of the last processed event (=nextIndex), which overlaps into the next measure.

isIncomplete

protected boolean isIncomplete

Whether the input data is exhausted and could not fill the currently recognized measure completely.

tailDiscarded

protected boolean tailDiscarded

Local flag that any synthetic very last event shall not be processed by the write out visitor.

nextIndex

protected int nextIndex

Index of the next event to process on the next call to getNext(). (In case of overlap, this is == the index of the last event in the current measure.)

nextMeasureStart

protected Rational nextMeasureStart

The start time point of the next measure, calculated by adding its length to the start of the last accepted measure.

Method Detail

byStartPoints

public static MetricConsumer byStartPoints(@Opt
                                           @Opt MSplitter metricSplitter,
                                           List<QualifiedRational> input)

Parameters:

metricSplitter - is the initial one, can be changed between to "hasNext()" accesses by changeMetrum(MSplitter).

input - a sorted list of relative time points (event start positions). The very first time point defines the start time of the very first measure. The very last time point is not an event, but the end of the event beginning at the next-to-last time point.

byStartPoints

public static MetricConsumer byStartPoints(@Opt
                                           @Opt MSplitter metricSplitter,
                                           List<Rational> input,
                                           boolean soundNotPause)

Factory method for a user. For details see byStartPoints(MSplitter, List).

Parameters:

soundNotPause - how all start points in "input" must be interpreted.

byDurations

public static MetricConsumer byDurations(@Opt
                                         @Opt MSplitter metricSplitter,
                                         List<QualifiedRational> input)

Factory method for a user.

Parameters:

metricSplitter - is the initial one, can be changed between to "hasNext()" accesses by changeMetrum(MSplitter). (Maybe == null initially, but must be set != null before the first split request.)

input - a list of durations. The very first time point will be mapped to "0/1" of the very first measure.

    input index   0      1     2                     3
       duration   dt0    dt1   dt2                   dt3
    input to MetricSplitter
       index      0      1     2        3            4
       startpoint 0.0    dt0   dt0+dt1  dt0+dt1+dt2  dt0+dt1+dt2+dt3
       duration     dt0     dt1   dt2       dt3
  

byDurations

public static MetricConsumer byDurations(@Opt
                                         @Opt MSplitter metricSplitter,
                                         List<Rational> input,
                                         boolean soundNotPause)

Factory method for a user. For details see byDurations(MSplitter, List).

Parameters:

soundNotPause - how all durations in "input" must be interpreted.

changeMetrum

public void changeMetrum(MSplitter newms)

Change the metric splitter and thus the meter to be used for the next splitting operations.

Parameters:

newms - must be fully instantiated with an MTreeSpec and all parameters.

hasNext

public boolean hasNext()

Whether there are unconsumed events, or at least one partially unconsumed event. Attention: the very last timepoint in "inputs" is not an event, but the end of the very last event.

hasCompleteNext

public boolean hasCompleteNext()

Whether there are unconsumed events, or at least one partially unconsumed event, which fill at least one complete measure, according to the currently set Metrum.
FIXME should fail if no MSplitter is set.

getResult

public MSplitter.Result getResult()

Returns the result of the last getNext() call to the metric splitter; for details see MetricSplitter.Result. But better use
this.new WriteOut().process()
, see MetricConsumer.WriteOut. Only this treats all cross-measure-bar situations correctly.

getResultIndex

public int getResultIndex()

The index of the first event in the current result measure, may be a trailing overlap from the last event in the preceding measure.

getMeasureStart

public Rational getMeasureStart()

Get the start of the current getResult measure. In case that durations are the input, a start with 0/1 is assumed. Otherwise the first measure starts with the first event, and the current time point corresponds to the input time points.

firstIsOverlap

public boolean firstIsOverlap()

Whether the first node in the current result (=event getResultIndex) is an overlap from the last measure.

getLastOverlap

public Rational getLastOverlap()

The length of the part of the last event of the current result which will overlap into the next measure.

isIncomplete

public boolean isIncomplete()

Whether the current measure is the very last, and its last event has been synthesized to fill it up.

discardSyntheticTail

public void discardSyntheticTail()

Discard the last event, which was only synthesized for completing the measure.

getRestDuration

public Rational getRestDuration()

The total of all events which have not yet been consumed. May be negative iff measure is the very last and incomplete.

getNextIndex

public int getNextIndex()

The index of the event which will be the first in the NEXT measure, i.e. after calling getNext(). (This may be the trailing rest of the last event of the current measure.)

getNextMeasureStart

public Rational getNextMeasureStart()

Get the end point the current getResult measure, ie. the start of the next measure after calling getNext(). In case that durations are the input, a start of the whole sequence at point 0/1 is assumed. Otherwise the first measure starts with the first event, and the current time point corresponds to the input time points.

getNext

public void getNext()

This method performs the metric analysis of a prefix of the input data, according to the currently selected metrum (see changeMetrum(MSplitter) and consumes as much as possible to fill one complete measure. After this call, the recognized prefix is the "current measure", and all inquiry methods are related to this situation.

This method prepares the time point data for a call to MSplitter. Its input (prepared in "Accu.Tps") must start with 0/1 and end exactly with the measure length. The very last measure is possibly extended to meet this criterion. The MSplitter WriteOut-Visitor is wrapped into the own MetricConsumer.WriteOut visitor, which treats the cross-measure-bar situations correctly.

Throws:

IllegalStateException - if the input is exhausted, ie. a call to hasNext() would return false.

NullpointerException - if not metrum has been selected (see changeMetrum(MSplitter)