Class MusicalTimeSpan

Represents a time span as a fraction of the whole note's length. More info in the Time and length: Representations: Musical article.

Inheritance

object

MusicalTimeSpan

Implements

ITimeSpan

IComparable

IComparable<MusicalTimeSpan>

IEquatable<MusicalTimeSpan>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Melanchall.DryWetMidi.Interaction

Assembly: Melanchall.DryWetMidi.dll

Syntax

public sealed class MusicalTimeSpan : ITimeSpan, IComparable, IComparable<MusicalTimeSpan>, IEquatable<MusicalTimeSpan>

Constructors

MusicalTimeSpan()

Initializes a new instance of the MusicalTimeSpan. The time span will be of zero size (0/1).

Declaration

public MusicalTimeSpan()

MusicalTimeSpan(long)

Initializes a new instance of the MusicalTimeSpan with the specified fraction of the whole note's length. The time span will be 1/fraction (for example, 1/4 if fraction is 4).

Declaration

public MusicalTimeSpan(long fraction)

Parameters

Type	Name	Description
long	fraction	The fraction of the whole note's length.

Exceptions

Type	Condition
ArgumentOutOfRangeException	fraction is zero or negative.

MusicalTimeSpan(long, long, bool)

Initializes a new instance of the MusicalTimeSpan with the specified numerator and denominator of the fraction of the whole note's length.

Declaration

public MusicalTimeSpan(long numerator, long denominator, bool simplify = true)

Parameters

Type	Name	Description
long	numerator	The numerator of fraction of the whole note's length.
long	denominator	The denominator of fraction of the whole note's length.
bool	simplify	true if the time span should be simplified, false otherwise.

Exceptions

Type	Condition
ArgumentOutOfRangeException	One of the following errors occurred: numerator is negative. denominator is zero or negative.

Fields

Eighth

MusicalTimeSpan that corresponds to the eighth length.

Declaration

public static readonly MusicalTimeSpan Eighth

Field Value

Type	Description
MusicalTimeSpan

Half

MusicalTimeSpan that corresponds to the half length.

Declaration

public static readonly MusicalTimeSpan Half

Field Value

Type	Description
MusicalTimeSpan

Quarter

MusicalTimeSpan that corresponds to the quarter length.

Declaration

public static readonly MusicalTimeSpan Quarter

Field Value

Type	Description
MusicalTimeSpan

Sixteenth

MusicalTimeSpan that corresponds to the sixteenth length.

Declaration

public static readonly MusicalTimeSpan Sixteenth

Field Value

Type	Description
MusicalTimeSpan

SixtyFourth

MusicalTimeSpan that corresponds to the sixty-fourth length.

Declaration

public static readonly MusicalTimeSpan SixtyFourth

Field Value

Type	Description
MusicalTimeSpan

ThirtySecond

MusicalTimeSpan that corresponds to the thirty-second length.

Declaration

public static readonly MusicalTimeSpan ThirtySecond

Field Value

Type	Description
MusicalTimeSpan

Whole

MusicalTimeSpan that corresponds to the whole length.

Declaration

public static readonly MusicalTimeSpan Whole

Field Value

Type	Description
MusicalTimeSpan

Properties

Denominator

Gets the denominator of the current MusicalTimeSpan.

Declaration

public long Denominator { get; }

Property Value

Type	Description
long

Numerator

Gets the numerator of the current MusicalTimeSpan.

Declaration

public long Numerator { get; }

Property Value

Type	Description
long

Methods

Add(ITimeSpan, TimeSpanMode)

Adds a time span to the current one.

Declaration

public ITimeSpan Add(ITimeSpan timeSpan, TimeSpanMode mode)

Parameters

Type	Name	Description
ITimeSpan	timeSpan	Time span to add to the current one.
TimeSpanMode	mode	Mode of the operation that defines meaning of time spans the operation will be performed on.

Returns

Type	Description
ITimeSpan	Time span that is a sum of the timeSpan and the current time span.

Remarks

If timeSpan and the current time span have the same type, the result time span will be of this type too; otherwise - of the MathTimeSpan.

Exceptions

Type	Condition
ArgumentNullException	timeSpan is invalid.
InvalidEnumArgumentException	mode specified an invalid value.

ChangeDenominator(long)

Changes denominator of the current MusicalTimeSpan.

Declaration

public MusicalTimeSpan ChangeDenominator(long denominator)

Parameters

Type	Name	Description
long	denominator	New denominator.

Returns

Type	Description
MusicalTimeSpan	An instance of the MusicalTimeSpan which represents the same time span as the original one but with the specified denominator.

Exceptions

Type	Condition
ArgumentOutOfRangeException	denominator is zero or negative.

Clone()

Clones the current time span.

Declaration

public ITimeSpan Clone()

Returns

Type	Description
ITimeSpan	Copy of the current time span.

CompareTo(MusicalTimeSpan)

Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object.

Declaration

public int CompareTo(MusicalTimeSpan other)

Parameters

Type	Name	Description
MusicalTimeSpan	other	An object to compare with this instance.

Returns

Type	Description
int	A value that indicates the relative order of the objects being compared. The return value has these meanings: Value Meaning Less than zero This instance precedes other in the sort order. Zero This instance occurs in the same position in the sort order as other. Greater than zero This instance follows other in the sort order.

CompareTo(object)

Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object.

Declaration

public int CompareTo(object other)

Parameters

Type	Name	Description
object	other	An object to compare with this instance.

Returns

Type	Description
int	A value that indicates the relative order of the objects being compared. The return value has these meanings: Value Meaning Less than zero This instance precedes other in the sort order. Zero This instance occurs in the same position in the sort order as other. Greater than zero This instance follows other in the sort order.

Divide(MusicalTimeSpan)

Divides the current time span by the specified MusicalTimeSpan returning ration between them.

Declaration

public double Divide(MusicalTimeSpan timeSpan)

Parameters

Type	Name	Description
MusicalTimeSpan	timeSpan	MusicalTimeSpan to divide the current time span by.

Returns

Type	Description
double	Ratio of the current MusicalTimeSpan and timeSpan.

Exceptions

Type	Condition
ArgumentNullException	timeSpan is null.
DivideByZeroException	timeSpan represents a time span of zero length.

Divide(double)

Shrinks the current time span by dividing its length by the specified divisor.

Declaration

public ITimeSpan Divide(double divisor)

Parameters

Type	Name	Description
double	divisor	Divisor to shrink the time span by.

Returns

Type	Description
ITimeSpan	Time span that is the current time span shrinked by the divisor.

Exceptions

Type	Condition
ArgumentOutOfRangeException	divisor is zero or negative.

Dotted(int)

Returns the current MusicalTimeSpan modified by the specified number of dots.

Declaration

public MusicalTimeSpan Dotted(int dotsCount)

Parameters

Type	Name	Description
int	dotsCount	The number of dots to modify the current MusicalTimeSpan.

Returns

Type	Description
MusicalTimeSpan	The dotted version of the current MusicalTimeSpan.

Exceptions

Type	Condition
ArgumentOutOfRangeException	dotsCount is negative.

DoubleDotted()

Returns the current MusicalTimeSpan modified by two dots.

Declaration

public MusicalTimeSpan DoubleDotted()

Returns

Type	Description
MusicalTimeSpan	The double dotted version of the current MusicalTimeSpan.

Duplet()

Returns a duplet based on the current MusicalTimeSpan.

Declaration

public MusicalTimeSpan Duplet()

Returns

Type	Description
MusicalTimeSpan	A duplet based on the current MusicalTimeSpan.

Equals(MusicalTimeSpan)

Indicates whether the current object is equal to another object of the same type.

Declaration

public bool Equals(MusicalTimeSpan other)

Parameters

Type	Name	Description
MusicalTimeSpan	other	An object to compare with this object.

Returns

Type	Description
bool	true if the current object is equal to the other parameter; otherwise, false.

Equals(object)

Determines whether the specified object is equal to the current object.

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
object	obj	The object to compare with the current object.

Returns

Type	Description
bool	true if the specified object is equal to the current object; otherwise, false.

Overrides

object.Equals(object)

FromDouble(double, DoubleToMusicalTimeSpanSettings)

Creates an instance of the MusicalTimeSpan from the specified double number. For example, 0.5 will be converted to the time span of 1/2, and 3/2 will be returned for the input number 1.5.

Declaration

public static MusicalTimeSpan FromDouble(double number, DoubleToMusicalTimeSpanSettings settings = null)

Parameters

Type	Name	Description
double	number	A number to convert to MusicalTimeSpan.
DoubleToMusicalTimeSpanSettings	settings	Settings which controls the process of conversion number to MusicalTimeSpan.

Returns

Type	Description
MusicalTimeSpan	An instance of the MusicalTimeSpan which represents the number.

Remarks

The method tries to build a stream of rationalizations of the number and returns the best one according to the settings.

Exceptions

Type	Condition
ArgumentOutOfRangeException	number is negative.
InvalidOperationException	Failed to find rationalization for the specified number. Try to refine settings.

GetHashCode()

Returns the hash code for this instance.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	A 32-bit signed integer hash code.

Overrides

object.GetHashCode()

Multiply(double)

Stretches the current time span by multiplying its length by the specified multiplier.

Declaration

public ITimeSpan Multiply(double multiplier)

Parameters

Type	Name	Description
double	multiplier	Multiplier to stretch the time span by.

Returns

Type	Description
ITimeSpan	Time span that is the current time span stretched by the multiplier.

Exceptions

Type	Condition
ArgumentOutOfRangeException	multiplier is negative.

Parse(string)

Converts the string representation of a whole note's fraction to its MusicalTimeSpan equivalent.

Declaration

public static MusicalTimeSpan Parse(string input)

Parameters

Type	Name	Description
string	input	A string containing a time span to convert.

Returns

Type	Description
MusicalTimeSpan	A MusicalTimeSpan equivalent to the time span contained in input.

Exceptions

Type	Condition
ArgumentException	input is null or contains white-spaces only.
FormatException	input has invalid format.

SingleDotted()

Returns the current MusicalTimeSpan modified by one dot.

Declaration

public MusicalTimeSpan SingleDotted()

Returns

Type	Description
MusicalTimeSpan	The single dotted version of the current MusicalTimeSpan.

Subtract(ITimeSpan, TimeSpanMode)

Subtracts a time span from the current one.

Declaration

public ITimeSpan Subtract(ITimeSpan timeSpan, TimeSpanMode mode)

Parameters

Type	Name	Description
ITimeSpan	timeSpan	Time span to subtract from the current one.
TimeSpanMode	mode	Mode of the operation that defines meaning of time spans the operation will be performed on.

Returns

Type	Description
ITimeSpan	Time span that is a difference between the timeSpan and the current time span.

Remarks

If timeSpan and the current time span have the same type, the result time span will be of this type too; otherwise - of the MathTimeSpan.

Exceptions

Type	Condition
ArgumentNullException	timeSpan is invalid.
InvalidEnumArgumentException	mode specified an invalid value.

ToString()

Returns a string that represents the current object.

Declaration

public override string ToString()

Returns

Type	Description
string	A string that represents the current object.

Overrides

object.ToString()

Triplet()

Returns a triplet based on the current MusicalTimeSpan.

Declaration

public MusicalTimeSpan Triplet()

Returns

Type	Description
MusicalTimeSpan	A triplet based on the current MusicalTimeSpan.

TryParse(string, out MusicalTimeSpan)

Converts the string representation of a whole note's fraction to its MusicalTimeSpan equivalent. A return value indicates whether the conversion succeeded.

Declaration

public static bool TryParse(string input, out MusicalTimeSpan timeSpan)

Parameters

Type	Name	Description
string	input	A string containing a time span to convert.
MusicalTimeSpan	timeSpan	When this method returns, contains the MusicalTimeSpan equivalent of the time span contained in input, if the conversion succeeded, or null if the conversion failed. The conversion fails if the input is null or Empty, or is not of the correct format. This parameter is passed uninitialized; any value originally supplied in result will be overwritten.

Returns

Type	Description
bool	true if input was converted successfully; otherwise, false.

Tuplet(int, int)

Returns a tuplet based on the current MusicalTimeSpan.

Declaration

public MusicalTimeSpan Tuplet(int tupletNotesCount, int tupletSpaceSize)

Parameters

Type	Name	Description
int	tupletNotesCount	Notes count of a tuplet to construct.
int	tupletSpaceSize	Space of a tuplet to construct.

Returns

Type	Description
MusicalTimeSpan	A tuplet based on the current MusicalTimeSpan.

Exceptions

Type	Condition
ArgumentOutOfRangeException	One of the following errors occurred: tupletNotesCount is zero or negative. tupletSpaceSize is zero or negative.

Operators

operator +(MusicalTimeSpan, MusicalTimeSpan)

Adds two specified MusicalTimeSpan instances.

Declaration

public static MusicalTimeSpan operator +(MusicalTimeSpan timeSpan1, MusicalTimeSpan timeSpan2)

Parameters

Type	Name	Description
MusicalTimeSpan	timeSpan1	The first MusicalTimeSpan to add.
MusicalTimeSpan	timeSpan2	The second MusicalTimeSpan to add.

Returns

Type	Description
MusicalTimeSpan	An object whose value is the sum of the values of timeSpan1 and timeSpan2.

Exceptions

Type	Condition
ArgumentNullException	One of the following errors occurred: timeSpan1 is null. timeSpan2 is null.

operator /(MusicalTimeSpan, long)

Divides the specified MusicalTimeSpan by a number.

Declaration

public static MusicalTimeSpan operator /(MusicalTimeSpan timeSpan, long number)

Parameters

Type	Name	Description
MusicalTimeSpan	timeSpan	The MusicalTimeSpan to divide by number.
long	number	The multiplier.

Returns

Type	Description
MusicalTimeSpan	An object whose value is the result of division of timeSpan by number.

Exceptions

Type	Condition
ArgumentNullException	timeSpan is null.
ArgumentOutOfRangeException	number is negative.

operator ==(MusicalTimeSpan, MusicalTimeSpan)

Determines if two MusicalTimeSpan objects are equal.

Declaration

public static bool operator ==(MusicalTimeSpan timeSpan1, MusicalTimeSpan timeSpan2)

Parameters

Type	Name	Description
MusicalTimeSpan	timeSpan1	The first MusicalTimeSpan to compare.
MusicalTimeSpan	timeSpan2	The second MusicalTimeSpan to compare.

Returns

Type	Description
bool	true if time spans are equal, false otherwise.

operator >(MusicalTimeSpan, MusicalTimeSpan)

Indicates whether a specified MusicalTimeSpan is greater than another one.

Declaration

public static bool operator >(MusicalTimeSpan timeSpan1, MusicalTimeSpan timeSpan2)

Parameters

Type	Name	Description
MusicalTimeSpan	timeSpan1	The first MusicalTimeSpan to compare.
MusicalTimeSpan	timeSpan2	The second MusicalTimeSpan to compare.

Returns

Type	Description
bool	true if the value of timeSpan1 is greater than the value of timeSpan2; otherwise, false.

Exceptions

Type	Condition
ArgumentNullException	One of the following errors occurred: timeSpan1 is null. timeSpan2 is null.

operator >=(MusicalTimeSpan, MusicalTimeSpan)

Indicates whether a specified MusicalTimeSpan is greater than or equal to another one.

Declaration

public static bool operator >=(MusicalTimeSpan timeSpan1, MusicalTimeSpan timeSpan2)

Parameters

Type	Name	Description
MusicalTimeSpan	timeSpan1	The first MusicalTimeSpan to compare.
MusicalTimeSpan	timeSpan2	The second MusicalTimeSpan to compare.

Returns

Type	Description
bool	true if the value of timeSpan1 is greater than or equal to the value of timeSpan2; otherwise, false.

Exceptions

Type	Condition
ArgumentNullException	One of the following errors occurred: timeSpan1 is null. timeSpan2 is null.

operator !=(MusicalTimeSpan, MusicalTimeSpan)

Determines if two MusicalTimeSpan objects are not equal.

Declaration

public static bool operator !=(MusicalTimeSpan timeSpan1, MusicalTimeSpan timeSpan2)

Parameters

Type	Name	Description
MusicalTimeSpan	timeSpan1	The first MusicalTimeSpan to compare.
MusicalTimeSpan	timeSpan2	The second MusicalTimeSpan to compare.

Returns

Type	Description
bool	false if time spans are equal, true otherwise.

operator <(MusicalTimeSpan, MusicalTimeSpan)

Indicates whether a specified MusicalTimeSpan is less than another one.

Declaration

public static bool operator <(MusicalTimeSpan timeSpan1, MusicalTimeSpan timeSpan2)

Parameters

Type	Name	Description
MusicalTimeSpan	timeSpan1	The first MusicalTimeSpan to compare.
MusicalTimeSpan	timeSpan2	The second MusicalTimeSpan to compare.

Returns

Type	Description
bool	true if the value of timeSpan1 is less than the value of timeSpan2; otherwise, false.

Exceptions

Type	Condition
ArgumentNullException	One of the following errors occurred: timeSpan1 is null. timeSpan2 is null.

operator <=(MusicalTimeSpan, MusicalTimeSpan)

Indicates whether a specified MusicalTimeSpan is less than or equal to another one.

Declaration

public static bool operator <=(MusicalTimeSpan timeSpan1, MusicalTimeSpan timeSpan2)

Parameters

Type	Name	Description
MusicalTimeSpan	timeSpan1	The first MusicalTimeSpan to compare.
MusicalTimeSpan	timeSpan2	The second MusicalTimeSpan to compare.

Returns

Type	Description
bool	true if the value of timeSpan1 is less than or equal to the value of timeSpan2; otherwise, false.

Exceptions

Type	Condition
ArgumentNullException	One of the following errors occurred: timeSpan1 is null. timeSpan2 is null.

operator *(MusicalTimeSpan, long)

Multiplies the specified MusicalTimeSpan by a number.

Declaration

public static MusicalTimeSpan operator *(MusicalTimeSpan timeSpan, long number)

Parameters

Type	Name	Description
MusicalTimeSpan	timeSpan	The MusicalTimeSpan to multiply by number.
long	number	The multiplier.

Returns

Type	Description
MusicalTimeSpan	An object whose value is the result of multiplication of timeSpan by number.

Exceptions

Type	Condition
ArgumentNullException	timeSpan is null.
ArgumentOutOfRangeException	number is negative.

operator *(long, MusicalTimeSpan)

Multiplies the specified MusicalTimeSpan by a number.

Declaration

public static MusicalTimeSpan operator *(long number, MusicalTimeSpan timeSpan)

Parameters

Type	Name	Description
long	number	The multiplier.
MusicalTimeSpan	timeSpan	The MusicalTimeSpan to multiply by number.

Returns

Type	Description
MusicalTimeSpan	An object whose value is the result of multiplication of timeSpan by number.

Exceptions

Type	Condition
ArgumentNullException	timeSpan is null.
ArgumentOutOfRangeException	number is negative.

operator -(MusicalTimeSpan, MusicalTimeSpan)

Subtracts a specified MusicalTimeSpan from another one.

Declaration

public static MusicalTimeSpan operator -(MusicalTimeSpan timeSpan1, MusicalTimeSpan timeSpan2)

Parameters

Type	Name	Description
MusicalTimeSpan	timeSpan1	The minuend.
MusicalTimeSpan	timeSpan2	The subtrahend.

Returns

Type	Description
MusicalTimeSpan	An object whose value is the result of the value of timeSpan1 minus the value of timeSpan2.

Exceptions

Type	Condition
ArgumentNullException	One of the following errors occurred: timeSpan1 is null. timeSpan2 is null.
ArgumentException	timeSpan1 is less than timeSpan2.

Implements

ITimeSpan

IComparable

IComparable<T>

IEquatable<T>

Extension Methods

TimeSpanUtilities.IsZeroTimeSpan(ITimeSpan)

TimeSpanUtilities.Round(ITimeSpan, TimeSpanRoundingPolicy, long, ITimeSpan, TempoMap)