Package eu.bandm.tscore.base

Class Util

java.lang.Object
eu.bandm.tscore.base.Util
public class Util extends Object
Collection of static utility methods.

  • Method Details

    • thePart

      @Opt public static @Opt Part thePart(TimeScape ts)
      Deliver the only part of the timescape object, if any, otherwise null.

    • partsToScores

      public static <D, P> Map<String,D> partsToScores(TimeScape ts, String topName, @Opt @Opt String scoreNameTemplate, MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg, @Opt P parameters, Function4<String,Part,MessageReceiver,P,D> constructorCall)
      Translate every "PART" section in a time scape object into one single score object each. If there is only one part, it gets the explicitly given "topname"; otherwise the scoreNameTemplate is expanded (by String.format(String,Object...)) to create the name from this explicit name and the name of the part in the score. Assumes that the names for the parts in one score are used unambiguously.
      Type Parameters:
      D - the type of the created score object
      P - the type of the additional optional creation parameters
      Parameters:
      ts - the time scape object (=tscore input file parse result)
      topName - the name to use if only only PART section is present in the source
      scoreNameTemplate - the string format template to combine "topName" and the name, the part is given in the score, if more than one part is contained.
      msg - passed to the constructor
      parameters - passed to the constructor
      constructorCall - must be a constructor with the arguments (1) name of the score to construct, (2) tscore part object to convert (3) message receiver (4) further optional construction parameters of an arbitrary type "P".

    • parseTimeScape

      public static TimeScape parseTimeScape(File in, Modifiers modifiers, MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg)
      Calls parseTimeScape(InputStream,String,Modifiers,MessageReceiver) with the canonical file name.

    • parseTimeScape

      public static TimeScape parseTimeScape(InputStream in, String sourceIndication, Modifiers modifiers, MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg)
      Applies tscore-raw-layer parser and delivers an tscore umod data model. Assume utf-8 encoding.
      Parameters:
      in - the input to be parsed.
      sourceIndication - to be used in error messages
      modifiers - configuration data, partly relevant for raw parsing process
      msg - receiver of logging and error messages

    • parseTimeScape

      public static TimeScape parseTimeScape(Reader in, String inputFileName, Modifiers modifiers, MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg)
      Applies tscore-raw-layer parser and delivers an tscore umod data model. Assume utf-8 encoding.
      Parameters:
      in - the input to be parsed.
      inputFileName - to be used in error messages
      modifiers - configuration data, partly relevant for raw parsing process
      msg - receiver of logging and error messages

    • fromStream

      @Opt public static <T> T fromStream(Class<T> cls, InputStream inputstream, String sourceIndication, Modifiers modifiers, MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg)
      ATTENTION only reads and converts part 0 !!
      Parameters:
      cls - must have a constructor with one single part and MessageReceiver, and a methode update()

    • fromFile

      @Opt public static <T> T fromFile(Class<T> cls, File inputfile, Modifiers modifiers, MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg)

    • checkIncreasing

      public static final <D> Function3<@Opt Comparator<? super D>,D,D,@Opt String> checkIncreasing()
      Checks whether two time points are strictly increasing; to be plugged into parseTpTops(). Returns null if okay, otherwise error message != null.

    • checkNotDecreasing

      public static final <D> Function3<Comparator<? super D>,D,D,@Opt String> checkNotDecreasing()
      Checks whether two time points are not decreasing; to be plugged into parseTpTops(). Returns null if okay, otherwise error message != null.

    • checkEqual

      public static final <D> Function3<Comparator<? super D>,D,D,@Opt String> checkEqual()
      Checks whether two time points are equal; to be plugged into parseTpTops(). Returns null if okay, otherwise error message != null.

    • singletonMap

      public static eu.bandm.tools.location.LocationMap<Object,eu.bandm.tools.util.xml.XMLDocumentIdentifier> singletonMap(String data, eu.bandm.tools.location.Location<eu.bandm.tools.util.xml.XMLDocumentIdentifier> sourceLoc)
      Constructs a LocationMap which points from the given String into the given location. Auxiliary function, needed e.g. when some input to a parser/lexer is locally pre-processed.

    • parseTpTops

      public static <T> void parseTpTops(MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg, Modifiers modifiers, Part part, Map<TpTop,T> values, SortedMap<T,TpTop> representatives, Translet.Parser<T> parser, @Opt @Opt Function3<Comparator<? super T>,T,T,@Opt String> check_oneLine, @Opt @Opt Function3<Comparator<? super T>,T,T,@Opt String> check_twoLines)
      Parse all TpTops into some internal numeric format "T" and store them. In this version each result from T may occur maximally once. This is the standard inside of one PART. (When unifying TpTops due to identical T-value, all subdivisions must be unified accordingly, which is NOT YET IMPLEMENTED)
      ATTENTION raw parser does unify TpTop-text in several lines into one data object, but DOES NOT preserve the original Location but the first. (Different to parameter values, which are stored into lists of tupels!) Therefore the diagnosis/location info looks slightly different (even wrong) in the rare case that tp-top source text is in more than one line, as in 
            T                 1h     1h
            59'59.0     0'     2'

      Parameters:
      values - output parameter where the T-values will be stored.
      representatives - backward map, stores one(1) TpTop for every computed T-value, namely the latest parsed.
      parser - Parser, generates possibly complicated error messages
      check_oneLine - check for two top values following in ONE time line. Typically a test for "strictly later". Iff ==null, no such check is performed.
      check_twoLines - check for last TpTop in one line and the first in the next line. Typically a test for "later or equal". Iff ==null, no such check is performed. FIXME use "PreImageMap values"instead of "values+representatives" ?!?!

    • eliminateLineBreaks

      public static <V> void eliminateLineBreaks(Part p, Map<TpTop,V> values)
      DOCME

    • shiftDivision

      public static void shiftDivision(TDivision td, Tp old, Tp now)
      Change the division to end at "now" and no longer at "old".

    • getRationalValue

      public static Rational getRationalValue(Function<TpTop,Rational> tptop2rat, Map<Tp,Rational> cache, Tp tp, MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg, Map<Rational,Tp> rat2tp)
      Translates abstract tp values into numeric values and maintains a second, backward cache. In this overlading it is a Map, for use cases where different Tps can yield only different Rational values. If this is violated, an error message is sent. As alternatives see getRationalValue(Function,Map,Tp), getRationalValue(Function,Map,Tp,Map), getRationalValue_lenient(Function,Map,Tp,Map), and getRationalValue(Function,Map,Tp,Multimap).
      Parameters:
      tptop2rat - how to calculate a Rational value from the text of a top time point.
      cache - from tscore time point objects to Rationals
      tp - the tscore time point object to convert into a Rational
      msg - receiver for error messages
      rat2tp - backward cache which maps each Rational to at most one time point object.

    • getRationalValue

      public static Rational getRationalValue(Function<TpTop,Rational> tptop2rat, Map<Tp,Rational> cache, Tp tp, Map<Rational,Tp> rat2tp)
      Translates abstract tp values into numeric values and maintains a second, backward cache. In this overlading it is a Map, for use cases where different Tps can yield only different Rational values. If this is violated, an IllegalArgumentException is thrown. As alternatives see getRationalValue(Function,Map,Tp,MessageReceiver,Map), getRationalValue(Function,Map,Tp), getRationalValue_lenient(Function,Map,Tp,Map), and getRationalValue(Function,Map,Tp,Multimap).
      Parameters:
      tptop2rat - how to calculate a Rational value from the text of a top time point.
      cache - from tscore time point objects to Rationals
      tp - the tscore time point object to convert into a Rational
      rat2tp - backward cache which maps each Rational to at most one time point object.

    • getRationalValue_lenient

      public static Rational getRationalValue_lenient(Function<TpTop,Rational> tptop2rat, Map<Tp,Rational> cache, Tp tp, Map<Rational,Tp> rat2tp)
      Translates abstract tp values into numeric values and maintains a second, backward cache. In this overlading it is a Map. Multiple time point objects may represent the same Rational, but only the first is stored in the backward cache. As alternatives see getRationalValue(Function,Map,Tp,MessageReceiver,Map), getRationalValue(Function,Map,Tp), getRationalValue(Function,Map,Tp,Map), and getRationalValue(Function,Map,Tp,Multimap).
      Parameters:
      tptop2rat - how to calculate a Rational value from the text of a top time point.
      cache - from tscore time point objects to Rationals
      tp - the tscore time point object to convert into a Rational
      rat2tp - backward cache which maps each Rational to at most one time point object.

    • getRationalValue

      public static Rational getRationalValue(Function<TpTop,Rational> tptop2rat, Map<Tp,Rational> cache, Tp tp, Multimap<Rational,Tp> rat2tp)
      Translates abstract tp values into numeric values and maintains a second, backward cache. In this overlading it is a Multimap, since different Tps can yield the same Rational value. As alternatives see getRationalValue(Function,Map,Tp,MessageReceiver,Map), getRationalValue(Function,Map,Tp), getRationalValue(Function,Map,Tp,Map), and getRationalValue_lenient(Function,Map,Tp,Map).
      Parameters:
      tptop2rat - how to calculate a Rational value from the text of a top time point.
      cache - from tscore time point objects to Rationals
      tp - the tscore time point object to convert into a Rational
      rat2tp - backward cache which maps each Rational to arbitrary many

    • getRationalValue

      public static Rational getRationalValue(Function<TpTop,Rational> tptop2rat, Map<Tp,Rational> cache, Tp tp)
      Central function for translating abstract tp values into numeric values by calculating an equi-distant sub-division recursively. Requires an interpretation function of only the top-level TpTops. A cache is maintained and used.
      If needed, an inverse map must be maintained by the caller, because it can be a Map (all Tp correspond to different Rational values) or a Multimap (different Tps can yield the same Rational value.) As alternatives see getRationalValue(Function,Map,Tp,MessageReceiver,Map), getRationalValue(Function,Map,Tp,Map), getRationalValue_lenient(Function,Map,Tp,Map), and getRationalValue(Function,Map,Tp,Multimap).
      Parameters:
      tptop2rat - translation for tptop objects
      cache -
      tp - the to to translate
      Returns:
      the Rational value of parameter tp

    • getLeftTpTop

      public static TpTop getLeftTpTop(Tp tp)
      Returns the highest TpTop lower or equal to the given Tp.

    • getRightTpTop

      public static TpTop getRightTpTop(Tp tp)
      Returns the lowest TpTop higher or equal to the given Tp.

    • getTpTopRelativeRational

      public static Rational getTpTopRelativeRational(Function<TpTop,Rational> tptop2rat, Map<Tp,Rational> cache, Tp tp)
      Returns the distance of the given Tp to the next left TpTop, which is in many cases its relative position in a measure, or sim.

    • commonDivider

      public static BigInteger commonDivider(Iterable<Rational> s)
      Calculates the greatest common divider of the denominators of the given Rationals.

    • unifyEventTimesByScalarValue

      public static <T> void unifyEventTimesByScalarValue(Map<T,Tp> representatives, Function<Tp,T> tp2t, Vox vox)
      ATTENTION: Different subdivisions are not unified automatically, e.g. when interpreted as Rational values. See 
          T            7        8  
    VOX a        b c d e  f
    VOX w        x   y    z
      Division by 4 in VOX a and by 2 in VOX w are not unified by default: the Tps of Event d and y are different (while having possibly the same Rational value, or sim.) The following function must be applied to all vox-es to patch the "when" fields and all access maps, if only one Tp object may represent a certain "T" value.
      Parameters:
      representatives - maps each occuring numeric time values to one Tp object. This map may serve as an input and / or as an output data.
      tp2t - function which calculates the numeric time value for any Tp object
      vox - voice object to process and (possibly) modify

    • getParamText

      @Opt public static @Opt String getParamText(Event ev, String trackname, String separator, eu.bandm.tools.location.LocationMap<Object,eu.bandm.tools.util.xml.XMLDocumentIdentifier> locs)
      Delivers the source text for a gvien parameter and a given event. If more than one lines are involved in the source, their contents are combined with the given separator String. For every fragment in ev.get_params()... it holds that length is >0 and content is non-blank. Therefore result!=null implies length>0 and (some) non-blank content.
      ((????? FIXME STIMMT NICHT »" "« ist möglich! ))

    • parseParamTrack

      public static void parseParamTrack(MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg, Vox v, String trackname, String separator, Translet.Parser<?> parser, Modifiers react)
      Applies a certain Translet.Parser parser to the given parameter track. The parser must contain the store operations required to deliver the results.
      Parameters:
      msg - The message receiver for error messages.
      v - the voice to parse
      trackname - non-empty string.
      separator - string for concatenating parameter values from several lines in the source file
      parser - given as an expression

    • classForName

      @Opt public static @Opt Class<?> classForName(@Opt @Opt String n)
      Delivers the class for a given name, iff existing.
      Parameters:
      n - the class name (completely qualified), may be null

    • parserForName

      @Opt public static <P> Translet.Parser<P> parserForName(@Opt @Opt String className, String parserName)
      Delivers the parser object for the members of a particular class.
      Parameters:
      className - the class name (completely qualified), may be null
      parserName - the name of the static method which delivers the parser. (in case of music: "membersParser")

    • range_respectingDomainOrder

      public static <A, B> Iterable<B> range_respectingDomainOrder(Multimap<A,B> data)
      Delivers an Iterator over the range of a Multimap which visits the range values in the order of the corresponding domain values. Assumes that domain HAS an order, and that this is realized technically by using a SortedMap as the "left" map when constructing the Multimap, eg. by using Util.Multimap_LTree. This is currently NOT CHECKED. FIXME

    • range_respectingDomainOrder

      public static <A, B> Iterable<B> range_respectingDomainOrder(SortedMap<A,B> data)
      Delivers an Iterator over the range of a Map which visits the range values in the order of the corresponding domain values. (This is only a wrapper around the standard behaviour of every SortedMap.

    • voiceFilter

      public static <E extends Event> Iterable<E> voiceFilter(Vox v, Iterable<E> it)
      An Iterables.FilterIterable over any Event Iterable which visits only those events of a given Vox.

    • voiceEvents

      public static Iterable<Event> voiceEvents(Vox v, Iterable<? extends Tp> tps)
      Creates an Iterable over all Events of a given Vox, when an Iterable over time points (Tp) is given.

    • haveParam

      public static <E extends Event> Iterable<E> haveParam(String pname, Iterable<E> it)
      Filter on Events which visits only those which have an (explicit, source level) value for a given parameter name.

    • keysOnly

      public static <E extends Event, F> Iterable<E> keysOnly(Map<E,F> map, Iterable<E> it)
      Filter on Events which visits only those which appear as key in the given map.

    • memoAdjacency

      public static void memoAdjacency(Iterable<Event> evs, Map<Event,Event> map, Event last)
      Stores the fact that two events are neighbours/adjacent into the Map.

    • memoEndTime

      public static void memoEndTime(Iterable<Event> evs, Map<Event,Tp> map, @Opt @Opt Tp last)
      Stores the start point of one event as the end point of its predecessor.
      Parameters:
      last - to be stored as the end point of the very last event

    • memoEndTime_ignoring

      public static void memoEndTime_ignoring(Iterable<Event> evs, Set<Event> ignore, Map<Event,Tp> map, Tp last)
      Stores the start point of one event as the end point of its predecessor, ignoring certain explicitly mentioned events.
      Parameters:
      last - to be stored as the end point of the very last event FIXME version with "Predicate" for ignoring will be more versatile !

    • findVoice

      public static Vox findVoice(Container ts, @Opt @Opt MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg, boolean generateErrors, String voiceName)
      Searches for the voice with the given name and generates messages if not found.
      Parameters:
      ts - either TimeScape or Part. ATTENTION, in TimeScape only timeless (meta-)data is contained. The "real" voices with events are only in Parts.
      generateErrors - whether to generate error messages, not only warnings

    • voicesExist

      public static boolean voicesExist(TimeScape ts, @Opt @Opt MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg, boolean generateErrors, String... voiceNames)
      Checks whether for each given voice name a voice object exists.
      Parameters:
      generateErrors - whether to generate error messages, not only warnings

    • noUnknownVoices

      public static boolean noUnknownVoices(TimeScape ts, @Opt @Opt MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg, boolean generateErrors, String... voiceNames)
      Checks whether no voice object exists with a name not explicitly given.
      Parameters:
      generateErrors - whether to generate error messages, not only warnings

    • firstLocation

      @Opt public static @Opt eu.bandm.tools.location.Location<eu.bandm.tools.util.xml.XMLDocumentIdentifier> firstLocation(Vox v)
      Returns the location of the first event in a voice, in source text order.

    • lastLocation

      @Opt public static @Opt eu.bandm.tools.location.Location<eu.bandm.tools.util.xml.XMLDocumentIdentifier> lastLocation(Vox v)
      Returns the location of the last event in a voice, in source text order.

    • warnUnusedParams

      public static void warnUnusedParams(MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg, Vox v, Set<String> analysed, boolean errorNotWarn)
      Emits a warning or an error if the source text of a voice contains parameters which are not analysed.
      Parameters:
      msg - drain of messages
      v - the voice
      analysed - set of parameter names which have been considered
      errorNotWarn - whether to produce an error message, not just a warning

    • veryFirstEventHasRequiredParameter

      public static <T> boolean veryFirstEventHasRequiredParameter(MessageReceiver<SimpleMessage<eu.bandm.tools.util.xml.XMLDocumentIdentifier>> msg, Event firstEv, Vox v, Map<Event,T> map, String pname)
      Checks whether the very first event of a particular voice has a necessary parameter.
      Parameters:
      msg - the message receiver for the error case
      firstEv - the event to check
      v - the voice, for error message only
      map - the parameter values, by events.
      pname - the name of the parameter, for error message only.

    • highestLowerBound

      @Opt public static <R, D> D highestLowerBound(SortedMap<R,D> map, R key)
      Returns the highest/largest key contained in the map which is lower or equal to tke given value. Maybe null.