Class: HeadMusic::Time::MusicalPosition

Inherits:
Object
  • Object
show all
Includes:
Comparable, RadixCarry
Defined in:
lib/head_music/time/musical_position.rb

Overview

Representation of a musical position in bars:beats:ticks:subticks notation

A MusicalPosition represents a point in musical time using a hierarchical structure:

  • bar: the measure number (1-indexed)
  • count: the count within the bar (1-indexed)
  • tick: subdivision of a beat (0-indexed, 960 ticks per quarter note)
  • subtick: finest resolution (0-indexed, 240 subticks per tick)

The position can be normalized according to a meter, which handles overflow by carrying excess values to higher levels (e.g., excess ticks become beats, excess beats become bars).

Examples:

Creating a position at bar 1, beat 1

position = HeadMusic::Time::MusicalPosition.new
position.to_s # => "1:1:0:0"

Parsing from a string

position = HeadMusic::Time::MusicalPosition.parse("2:3:480:0")
position.bar # => 2
position.count # => 3

Normalizing with overflow

meter = HeadMusic::Rudiment::Meter.get("4/4")
position = HeadMusic::Time::MusicalPosition.new(1, 1, 960, 0)
position.normalize!(meter)
position.to_s # => "1:2:0:0" (ticks carried into beats)

Comparing positions

pos1 = HeadMusic::Time::MusicalPosition.new(1, 1, 0, 0)
pos2 = HeadMusic::Time::MusicalPosition.new(1, 2, 0, 0)
meter = HeadMusic::Rudiment::Meter.get("4/4")
pos1.normalize!(meter)
pos2.normalize!(meter)
pos1 < pos2 # => true

Constant Summary collapse

DEFAULT_FIRST_BAR =

Default starting bar number

1
FIRST_COUNT =

First count in a bar

1
FIRST_TICK =

First tick in a beat

0
FIRST_SUBTICK =

First subtick in a tick

0

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(bar = DEFAULT_FIRST_BAR, count = FIRST_COUNT, tick = FIRST_TICK, subtick = FIRST_SUBTICK) ⇒ MusicalPosition

Create a new musical position

Parameters:

  • bar (Integer, String) (defaults to: DEFAULT_FIRST_BAR) —

    the bar number (default: 1)

  • count (Integer, String) (defaults to: FIRST_COUNT) —

    the count number (default: 1)

  • tick (Integer, String) (defaults to: FIRST_TICK) —

    the tick number (default: 0)

  • subtick (Integer, String) (defaults to: FIRST_SUBTICK) —

    the subtick number (default: 0)



87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/head_music/time/musical_position.rb', line 87

def initialize(
  bar = DEFAULT_FIRST_BAR,
  count = FIRST_COUNT,
  tick = FIRST_TICK,
  subtick = FIRST_SUBTICK
)
  @bar = bar.to_i
  @count = count.to_i
  @tick = tick.to_i
  @subtick = subtick.to_i
end

Instance Attribute Details

#bar ⇒ Integer (readonly)

Returns the bar (measure) number (1-indexed).

Returns:

  • (Integer) —

    the bar (measure) number (1-indexed)



45
46
47
 
# File 'lib/head_music/time/musical_position.rb', line 45

def bar
  @bar
end

#count ⇒ Integer (readonly)

A count, not a beat: Meter distinguishes the two, and in 6/8 there are two beats and six counts. A position addresses the latter.

Returns:

  • (Integer) —

    the count within the bar (1-indexed)



51
52
53
 
# File 'lib/head_music/time/musical_position.rb', line 51

def count
  @count
end

#subtick ⇒ Integer (readonly)

Returns the subtick within the tick (0-indexed).

Returns:

  • (Integer) —

    the subtick within the tick (0-indexed)



57
58
59
 
# File 'lib/head_music/time/musical_position.rb', line 57

def subtick
  @subtick
end

#tick ⇒ Integer (readonly)

Returns the tick within the beat (0-indexed).

Returns:

  • (Integer) —

    the tick within the beat (0-indexed)



54
55
56
 
# File 'lib/head_music/time/musical_position.rb', line 54

def tick
  @tick
end

Class Method Details

.parse(identifier) ⇒ MusicalPosition

Parse a position from a string representation

Examples:

MusicalPosition.parse("2:3:480:120")

Parameters:

  • identifier (String) —

    position in "bar:count:tick:subtick" format

Returns:



77
78
79
 
# File 'lib/head_music/time/musical_position.rb', line 77

def self.parse(identifier)
  new(*identifier.scan(/\d+/)[0..3])
end

Instance Method Details

#<=>(other) ⇒ Integer

Compare this position to another

Positions compare lexically on [bar, count, tick, subtick]. Elapsed time is deliberately not consulted: a position is a coordinate, and converting it to a duration requires the meter of every intervening bar, which only a meter map knows. Ordering two normalized positions needs no such knowledge.

Parameters:

Returns:

  • (Integer) —

    -1 if less than, 0 if equal, 1 if greater than



147
148
149
 
# File 'lib/head_music/time/musical_position.rb', line 147

def <=>(other)
  to_a <=> other.to_a
end

#carry(component, radix, first: 0) ⇒ Integer (private) Originally defined in module RadixCarry

Divide the named component by its radix, store the remainder back, and return the amount to carry into the next-higher component.

A 1-indexed component (a beat, whose values run 1..radix) is shifted into 0-indexed space before the divmod and back afterward, so that the last value in the range stays put instead of carrying.

Parameters:

  • first (Integer) (defaults to: 0) —

    the component's lowest valid value

Returns:

  • (Integer) —

    the carry (may be negative when borrowing)

#eql?(other) ⇒ Boolean

Returns true when other is a position with the same components.

Parameters:

  • other (Object) —

    the object to compare

Returns:

  • (Boolean) —

    true when other is a position with the same components



158
159
160
 
# File 'lib/head_music/time/musical_position.rb', line 158

def eql?(other)
  other.is_a?(self.class) && to_a == other.to_a
end

#hash ⇒ Integer

Returns a hash over the position's components.

Returns:

  • (Integer) —

    a hash over the position's components



152
153
154
 
# File 'lib/head_music/time/musical_position.rb', line 152

def hash
  to_a.hash
end

#normalize!(meter) ⇒ self

Normalize the position according to a meter, handling overflow

This method modifies the position in place, carrying excess values from lower levels to higher levels (subticks → ticks → beats → bars). Also handles negative values by borrowing from higher levels.

Examples:

meter = HeadMusic::Rudiment::Meter.get("4/4")
position = MusicalPosition.new(1, 1, 960, 240)
position.normalize!(meter) # => "1:2:1:0"

Parameters:

Returns:

  • (self) —

    returns self for method chaining



125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/head_music/time/musical_position.rb', line 125

def normalize!(meter)
  return self unless meter

  # Carry overflow (and borrow underflow) up through each level.
  # divmod handles both in-range and out-of-range values uniformly.
  @tick += carry(:subtick, HeadMusic::Time::SUBTICKS_PER_TICK)
  @count += carry(:tick, meter.ticks_per_count)
  @bar += carry(:count, meter.counts_per_bar, first: FIRST_COUNT)

  self
end

#to_a ⇒ Array<Integer>

Convert position to array format

Returns:

  • (Array<Integer>) —

    [bar, count, tick, subtick]



102
103
104
 
# File 'lib/head_music/time/musical_position.rb', line 102

def to_a
  [bar, count, tick, subtick]
end

#to_s ⇒ String

Convert position to string format

Returns:

  • (String) —

    position in "bar:count:tick:subtick" format



109
110
111
 
# File 'lib/head_music/time/musical_position.rb', line 109

def to_s
  "#{bar}:#{count}:#{tick}:#{subtick}"
end