Class: HeadMusic::Time::ClockPosition

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

Overview

A value object representing elapsed nanoseconds of clock time

ClockPosition provides a high-precision representation of time elapsed from a reference point, stored as nanoseconds. This allows for precise temporal calculations in musical contexts where millisecond-level accuracy is required for MIDI timing, audio synchronization, and SMPTE timecode.

Examples:

Creating a position at one second

position = HeadMusic::Time::ClockPosition.new(1_000_000_000)
position.to_seconds # => 1.0

Adding two positions together

pos1 = HeadMusic::Time::ClockPosition.new(500_000_000)
pos2 = HeadMusic::Time::ClockPosition.new(300_000_000)
result = pos1 + pos2
result.to_milliseconds # => 800.0

Comparing positions

early = HeadMusic::Time::ClockPosition.new(1_000_000_000)
late = HeadMusic::Time::ClockPosition.new(2_000_000_000)
early < late # => true

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(nanoseconds) ⇒ ClockPosition

Create a new clock position

Parameters:

  • nanoseconds (Integer) —

    the number of nanoseconds elapsed



35
36
37
 
# File 'lib/head_music/time/clock_position.rb', line 35

def initialize(nanoseconds)
  @nanoseconds = nanoseconds
end

Instance Attribute Details

#nanoseconds ⇒ Integer (readonly)

Returns the number of nanoseconds since the reference point.

Returns:

  • (Integer) —

    the number of nanoseconds since the reference point



30
31
32
 
# File 'lib/head_music/time/clock_position.rb', line 30

def nanoseconds
  @nanoseconds
end

Instance Method Details

#+(other) ⇒ ClockPosition

Add another clock position to this one

Parameters:

Returns:



71
72
73
 
# File 'lib/head_music/time/clock_position.rb', line 71

def +(other)
  self.class.new(nanoseconds + other.to_i)
end

#<=>(other) ⇒ Integer

Compare this position to another

Parameters:

Returns:

  • (Integer) —

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



79
80
81
 
# File 'lib/head_music/time/clock_position.rb', line 79

def <=>(other)
  nanoseconds <=> other.to_i
end

#to_i ⇒ Integer

Convert to integer representation (nanoseconds)

Returns:

  • (Integer) —

    nanoseconds



42
43
44
 
# File 'lib/head_music/time/clock_position.rb', line 42

def to_i
  nanoseconds
end

#to_microseconds ⇒ Float

Convert nanoseconds to microseconds

Returns:

  • (Float) —

    elapsed microseconds



49
50
51
 
# File 'lib/head_music/time/clock_position.rb', line 49

def to_microseconds
  nanoseconds / 1_000.0
end

#to_milliseconds ⇒ Float

Convert nanoseconds to milliseconds

Returns:

  • (Float) —

    elapsed milliseconds



56
57
58
 
# File 'lib/head_music/time/clock_position.rb', line 56

def to_milliseconds
  nanoseconds / 1_000_000.0
end

#to_seconds ⇒ Float

Convert nanoseconds to seconds

Returns:

  • (Float) —

    elapsed seconds



63
64
65
 
# File 'lib/head_music/time/clock_position.rb', line 63

def to_seconds
  nanoseconds / 1_000_000_000.0
end