Class: Horologium::ScaleReading

Inherits:
Object
  • Object
show all
Defined in:
lib/horologium/scale_reading.rb,
sig/horologium/scale_reading.rbs

Overview

An instant seen in one time scale. It is what Instant#to returns.

An instant is a point on the timeline and knows no scale; to chooses the scale it is read in, and as chooses the shape it comes out in. A reading is frozen, and keeps the precision of the instant it came from.

Examples:

instant = Horologium::Instant.from_julian_date(2_443_144.5, scale: :tai)
instant.to(:tt).as(:julian_date) # => 2443144.5003725

Constant Summary collapse

REPRESENTATIONS =

The representations a reading can be taken as.

Returns:

{
  julian_date: Representations::JulianDate,
  modified_julian_date: Representations::ModifiedJulianDate,
  civil: Representations::Civil,
  iso8601: Representations::Iso8601
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(scale, value, precision, provenance = :measured) ⇒ ScaleReading

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of ScaleReading.

Parameters:

Raises:

  • (ArgumentError) —

    when the value does not match the precision, which is how a scale that dropped the precision it was given is caught



54
55
56
57
58
59
60
61
62
 
# File 'lib/horologium/scale_reading.rb', line 54

def initialize(scale, value, precision, provenance = :measured)
  Numeric::Precision.validate_value!(value, precision)

  @scale = scale
  @value = value
  @precision = precision
  @provenance = provenance
  freeze
end

Instance Attribute Details

#precision ⇒ Symbol (readonly)

The precision, carried over from the instant.

Returns:

  • (Symbol) —

    :standard or :exact



30
31
32
 
# File 'lib/horologium/scale_reading.rb', line 30

def precision
  @precision
end

#provenance ⇒ Symbol (readonly)

How well founded the reading is. :measured for a reading that rests on constants, models, or confirmed data; :extrapolated for a UTC reading past the point its leap second data vouches for, where the offset is the last known one and a new leap second could overturn it.

Returns:

  • (Symbol) —

    :measured or :extrapolated



44
45
46
 
# File 'lib/horologium/scale_reading.rb', line 44

def provenance
  @provenance
end

#scale ⇒ Symbol (readonly)

The scale the instant is read in.

Returns:

  • (Symbol) —

    the registered name of the scale, such as :tt



25
26
27
 
# File 'lib/horologium/scale_reading.rb', line 25

def scale
  @scale
end

#value ⇒ Horologium::Numeric::TwoPartFloat, Horologium::Numeric::Exact (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

The Julian Date in this scale, in days.

Returns:



36
37
38
 
# File 'lib/horologium/scale_reading.rb', line 36

def value
  @value
end

Instance Method Details

#==(other) ⇒ Boolean

Same scale, same moment in it, whatever precision each carries. This is how Instant compares.

Parameters:

  • other (Object)

Returns:

  • (Boolean) 


95
96
97
98
99
 
# File 'lib/horologium/scale_reading.rb', line 95

def ==(other)
  other.is_a?(ScaleReading) &&
    scale == other.scale &&
    value.to_r == other.value.to_r
end

#as(representation, as: :float) ⇒ Object

The reading, in the representation asked for. The whole reading is handed to the representation, not only the value, because a representation may need the scale to render it. A civil date in UTC has to ask the scale whether the day it falls in holds a leap second.

Examples:

instant = Horologium::Instant.from_julian_date(2_443_144.5, scale: :tai)
instant.to(:tt).as(:julian_date, as: :rational)

Parameters:

  • representation (Symbol) —

    one of the keys of REPRESENTATIONS

  • as (Symbol) (defaults to: :float) —

    the type to come out as, passed on to the representation; :float, :rational, or :two_part for a Julian Date

  • as: (Symbol) (defaults to: :float)

Returns:

  • (Object) —

    the reading, in that representation

Raises:



81
82
83
84
85
86
87
88
 
# File 'lib/horologium/scale_reading.rb', line 81

def as(representation, as: :float)
  REPRESENTATIONS.fetch(representation) {
    raise UnknownRepresentationError.new(
      representation,
      REPRESENTATIONS.keys
    )
  }.render(self, as)
end

#eql?(other) ⇒ Boolean

Stricter than ==: the precision must match too.

Parameters:

  • other (Object)

Returns:

  • (Boolean) 


105
106
107
 
# File 'lib/horologium/scale_reading.rb', line 105

def eql?(other)
  self == other && precision == other.precision
end

#hash ⇒ Integer

Returns a hash matching #eql?.

Returns:

  • (Integer) —

    a hash matching #eql?



110
111
112
 
# File 'lib/horologium/scale_reading.rb', line 110

def hash
  [self.class, scale, precision, value.to_r].hash
end

#inspect ⇒ String

Returns:

  • (String) 


115
116
117
118
119
120
121
122
123
124
 
# File 'lib/horologium/scale_reading.rb', line 115

def inspect
  format(
    "#<%s %s JD in %s (%s, %s)>",
    self.class,
    value.to_f,
    scale,
    precision,
    provenance
  )
end