RationalDuration (BandM signal & music)

java.lang.Object
- eu.bandm.music.entities.RationalDuration

All Implemented Interfaces:

DurationIndication, Comparable<RationalDuration>
```
public class RationalDuration
extends Object
implements DurationIndication, Comparable<RationalDuration>
```
Implements the fundamental duration domain in CWN, namely durations expressed by rational numbers. These rational numbers represent durations in the "abstract CWN time". The Rational "1/4" corresponds to the abstract duration notated as a "quarter note", "3/8" to a "dotted quarter note", and "1/6" to a "quarter note under a triplet bracket", etc.

This class also provides
- static auxiliary methods for duration calculation.
- an auxiliary static class RationalDuration.DottedBaseDuration, which represents the combination of basic note symbols and Prolongation Dots.
- static methods for calculating "free sectionings" ("FS"), which are minimal sequences of RationalDuration.DottedBaseDuration.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`RationalDuration.DottedBaseDuration` Convenience class which allows to retrieve base value, effective value, dot count, dots as a text string, etc.

Field Summary

Fields
Modifier and Type	Field and Description
`protected static Map<Rational,RationalDuration.DottedBaseDuration>`	`cache_dotted` Maps from rational duration values to the representing dotted notation.
`protected static Map<Integer,PrimeFactors>`	`cache_int` A cache for the prime factors of the integers serving as key.
`protected static Map<Integer,Integer>`	`cache_nearest_pot` Caches the nearest power of two, as found by the algorithm {@link #nearest_power_of_two(int):
`protected static Map<Rational,PrimeFactors>`	`cache_rat` A cache for the prime factors of the rationals.
`static Translet.Parser<RationalDuration>`	`parser` Evident
`static RationalDuration`	`QUARTER` The duration of a quarter note = 1/4
`(package private) Rational`	`rat` The rational value of the duration.
`static RetractableFunction<RationalDuration,Rational>`	`toRational` retract .
`static RationalDuration`	`WHOLE` The duration of a whole note = 1/1
`static RationalDuration`	`ZERO` Evident

Constructor Summary

Constructors
Constructor and Description
`RationalDuration(int num, int den)` Make a duration n/d for n>=0 and d>0.
`RationalDuration(Rational rat)` Make a duration for rat>=0/1.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static List<Integer>`	`binarySectioning(int i)` Returns the unique descending list of powers of two which sum up to the argument.
`int`	`compareTo(RationalDuration o)`
`static @Opt RationalDuration.DottedBaseDuration`	`dottedNotation(Rational rat)` Return the representation as base duration plus zero or more DOTs, or null if no such exists.
`static @Opt RationalDuration.DottedBaseDuration`	`dottedNotation(RationalDuration d)` Return the duration's representation as base duration plus zero or more DOTs,
`static boolean`	`e_writable(int enumerator, int maxdots)` Quick test whether a numerator alone is writable as `RationalDuration.DottedBaseDuration`, with given maximal dot count.
`boolean`	`equals(Object o)`
`static RationalDuration`	`fromRational(Rational rat)`
`static int`	`highest_odd_factor(int value)` Divides repeatedly by 2 as long as the result is even.
`static boolean`	`isPowerOfTwo(int i)` Whether an integer is a power of two.
`static boolean`	`isPowerOfTwo(Rational rat)` Returns true for 1/n or n/1, with n power of two(2), including 0/1.
`static int`	`logTwo(int i)` Delivers the exponent of two.
`static int`	`nearest_power_of_two(int i)` Used to find the most sensible denominator for to introduce a proportion with the numerator i.
`static int`	`nextNotLowerPowerOfTwo(int i)` Returns the next power of two which is not lower than the argument.
`static PrimeFactors`	`primeFactors_mod_2(BigInteger value)`
`static PrimeFactors`	`primeFactors_mod_2(int value)` Delivers a `PrimeFactors` object after removing all powers of two(2), since these are ubiquituous in CWN notation and not subject to dedicated calculation.
`static PrimeFactors`	`primeFactors_mod_2(Rational value)` Delivers a `PrimeFactors` object after removing all powers of two(2), since these are ubiquituous in CWN notation and not subject to dedicated calculation.
`Rational`	`toRational()` Returns the "Notated CWN Duration", which is a rational, standing for a note duration (1/4 for a quater note, 3/8 for a dotted quater note, etc.)
`String`	`toString()` Same as `Rational.toString()`.
`protected static int`	`x_nearest_power_of_two(int i)` Internal aux function.

Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - cache_int
```
protected static Map<Integer,PrimeFactors> cache_int
```
    A cache for the prime factors of the integers serving as key.
  - cache_rat
```
protected static Map<Rational,PrimeFactors> cache_rat
```
    A cache for the prime factors of the rationals. These are the positive exponents of the prime factors of the numerator and the negative exponents of the prime factors of the denominator.
  - cache_dotted
```
protected static final Map<Rational,RationalDuration.DottedBaseDuration> cache_dotted
```
    Maps from rational duration values to the representing dotted notation. There is at most one. If none exists, a null is stored.
  - cache_nearest_pot
```
protected static final Map<Integer,Integer> cache_nearest_pot
```
    Caches the nearest power of two, as found by the algorithm {@link #nearest_power_of_two(int):
  - rat
```
final Rational rat
```
    The rational value of the duration.
  - ZERO
```
public static final RationalDuration ZERO
```
    Evident
  - WHOLE
```
public static final RationalDuration WHOLE
```
    The duration of a whole note = 1/1
  - QUARTER
```
public static final RationalDuration QUARTER
```
    The duration of a quarter note = 1/4
  - toRational
```
public static RetractableFunction<RationalDuration,Rational> toRational
```
    retract . apply == id
  - parser
```
public static final Translet.Parser<RationalDuration> parser
```
    Evident
- Constructor Detail
  - RationalDuration
```
public RationalDuration(int num,
                        int den)
```
    Make a duration n/d for n>=0 and d>0.
  - RationalDuration
```
public RationalDuration(Rational rat)
```
    Make a duration for rat>=0/1.
- Method Detail
  - primeFactors_mod_2
```
public static PrimeFactors primeFactors_mod_2(int value)
```
    Delivers a PrimeFactors object after removing all powers of two(2), since these are ubiquituous in CWN notation and not subject to dedicated calculation.
  - primeFactors_mod_2
```
public static PrimeFactors primeFactors_mod_2(BigInteger value)
```
    See Also:
    
    primeFactors_mod_2(int)
  - primeFactors_mod_2
```
public static PrimeFactors primeFactors_mod_2(Rational value)
```
    Delivers a PrimeFactors object after removing all powers of two(2), since these are ubiquituous in CWN notation and not subject to dedicated calculation.
  - highest_odd_factor
```
public static int highest_odd_factor(int value)
```
    Divides repeatedly by 2 as long as the result is even.
  - dottedNotation
```
@Opt
public static @Opt RationalDuration.DottedBaseDuration dottedNotation(Rational rat)
```
    Return the representation as base duration plus zero or more DOTs, or null if no such exists. The denominator must be a power of two(2). The enumerator must be one less than a power of two(2). Then (e+1/d*2) is the base value, and ld(e+1)-1 is the dot count. Eg.
```
       rat      nextFullNote
       factors  nextFactors    
         7         8     1      1            8 => 2^3 => 2 is dot count
(rat=)  --    =>  -- =   -  =>  - (=base) 
        16        16     2      4  

         3         4     1      1            4 => 2^2 => 1 is dot count
(rat=)  --    => --- =   -  => -- 
        32        32     8     16 

         1         2     1      1            2 => 2^1 => 0 is dot count
(rat=)  --    => --- =   -  => -- 
         8         8     4      8 

  
```
  - dottedNotation
```
@Opt
public static @Opt RationalDuration.DottedBaseDuration dottedNotation(RationalDuration d)
```
    Return the duration's representation as base duration plus zero or more DOTs,
    
    See Also:
    
    dottedNotation(Rational)
  - e_writable
```
public static boolean e_writable(int enumerator,
                                 int maxdots)
```
    Quick test whether a numerator alone is writable as RationalDuration.DottedBaseDuration, with given maximal dot count. (This is called "e-writable". If dot-count==0, it is even "d-writable"). This test is sensible, since prime factors in the denominator must be eliminated anyhow (by some proportional bracket). So all durations with a numerator of (2^x)*[(2^n)-1] are writable in one single symbol, using (n-1) dots:
```
  1/2  -> 0 dots   1+1 = 2^1     = 00 0010
  3/4  -> 1 dot    3+1 = 2^2     = 00 0100
  7/8  -> 2 dots   7+1 = 2^3     = 00 1000
  
```
  - nearest_power_of_two
```
public static int nearest_power_of_two(int i)
```
    Used to find the most sensible denominator for to introduce a proportion with the numerator i. Assumes i>0. The middle of the interval between two powers of two is mapped upward, but not 3, which is mapped downward:
```
  |  |  ,  |     ,      |             ,               |                ,         |
  1  2  3  4  5  6  7   8  9  10  11  12  13  14  15  16  17  18 .. 23 24  25 .. 32 
  1  2  2  4  4  8  8   8  8   8   8  16  16  16  16  16  16  16    16 32  32    32
  
```
    So you get proportions like 5/4, 7/8, 11/8, 17/16, 33/32.
  - x_nearest_power_of_two
```
protected static int x_nearest_power_of_two(int i)
```
    Internal aux function. @see nearest_power_of_two(int).
  - isPowerOfTwo
```
public static boolean isPowerOfTwo(int i)
```
    Whether an integer is a power of two. Only defined for positive integers (>=0). Zero returns false.
  - nextNotLowerPowerOfTwo
```
public static int nextNotLowerPowerOfTwo(int i)
```
    Returns the next power of two which is not lower than the argument. Only defined for positive integers (>=0).
  - logTwo
```
public static int logTwo(int i)
```
    Delivers the exponent of two. Only defined if the argument indeed is a power of two. Only defined for positive integers (>0).
  - isPowerOfTwo
```
public static boolean isPowerOfTwo(Rational rat)
```
    Returns true for 1/n or n/1, with n power of two(2), including 0/1.
  - binarySectioning
```
public static List<Integer> binarySectioning(int i)
```
    Returns the unique descending list of powers of two which sum up to the argument.
  - toString
```
public String toString()
```
    Same as Rational.toString().
    
    Overrides:
    
    toString in class Object
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - compareTo
```
public int compareTo(RationalDuration o)
```
    Specified by:
    
    compareTo in interface Comparable<RationalDuration>
  - toRational
```
public Rational toRational()
```
    Description copied from interface: DurationIndication
    
    Returns the "Notated CWN Duration", which is a rational, standing for a note duration (1/4 for a quater note, 3/8 for a dotted quater note, etc.)
    
    Specified by:
    
    toRational in interface DurationIndication
  - fromRational
```
public static RationalDuration fromRational(Rational rat)
```

Class RationalDuration

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

cache_int

cache_rat

cache_dotted

cache_nearest_pot

rat

ZERO

WHOLE

QUARTER

toRational

parser

Constructor Detail

RationalDuration

RationalDuration

Method Detail

primeFactors_mod_2

primeFactors_mod_2

primeFactors_mod_2

highest_odd_factor

dottedNotation

dottedNotation

e_writable

nearest_power_of_two

x_nearest_power_of_two

isPowerOfTwo

nextNotLowerPowerOfTwo

logTwo

isPowerOfTwo

binarySectioning

toString

equals

compareTo

toRational

fromRational