Module: Horologium

Defined in:
lib/horologium.rb,
lib/horologium/error.rb,
lib/horologium/instant.rb,
lib/horologium/version.rb,
lib/horologium/duration.rb,
lib/horologium/scales/tt.rb,
lib/horologium/scales/tai.rb,
lib/horologium/scales/tdb.rb,
lib/horologium/scales/utc.rb,
lib/horologium/scales/base.rb,
lib/horologium/configuration.rb,
lib/horologium/numeric/exact.rb,
lib/horologium/precise_value.rb,
lib/horologium/scale_reading.rb,
lib/horologium/data/leap_seconds.rb,
lib/horologium/numeric/precision.rb,
lib/horologium/representations/civil.rb,
lib/horologium/data/barycentric_model.rb,
lib/horologium/numeric/two_part_float.rb,
lib/horologium/representations/iso8601.rb,
lib/horologium/representations/civil_time.rb,
lib/horologium/representations/julian_date.rb,
lib/horologium/representations/modified_julian_date.rb,
sig/horologium.rbs,
sig/horologium/instant.rbs,
sig/horologium/numeric.rbs,
sig/horologium/duration.rbs,
sig/horologium/scales/tt.rbs,
sig/horologium/scales/tai.rbs,
sig/horologium/scales/tdb.rbs,
sig/horologium/scales/utc.rbs,
sig/horologium/scales/base.rbs,
sig/horologium/configuration.rbs,
sig/horologium/numeric/exact.rbs,
sig/horologium/precise_value.rbs,
sig/horologium/scale_reading.rbs,
sig/horologium/data/leap_seconds.rbs,
sig/horologium/numeric/precision.rbs,
sig/horologium/representations/civil.rbs,
sig/horologium/data/barycentric_model.rbs,
sig/horologium/numeric/two_part_float.rbs,
sig/horologium/representations/iso8601.rbs,
sig/horologium/representations/civil_time.rbs,
sig/horologium/representations/julian_date.rbs,
sig/horologium/representations/modified_julian_date.rbs

Overview

Horologium is a Ruby library dedicated to scientific time: the time scales, high-precision instants, Julian Dates, intervals, and rigorous conversions between scales.

Defined Under Namespace

Modules: Data, Numeric, PreciseValue, Representations, Scales Classes: Configuration, ConfigurationError, DimensionalError, Duration, Error, Instant, InvalidCivilTimeError, OutOfDataRangeError, OutOfRangeError, ParseError, ScaleReading, UnknownOutputError, UnknownPrecisionError, UnknownRepresentationError, UnknownScaleError

Constant Summary collapse

VERSION =

Returns:

  • (String) 
"0.0.3"
CONFIGURATION_LOCK =

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

Guards the one-time build of the configuration, so two threads reaching it at once cannot each build one and lose the other's scales.

Returns:

  • (Thread::Mutex) 
Mutex.new

Class Method Summary collapse

Class Method Details

.configuration ⇒ Configuration

The configuration is built on the first read, under a lock, so that two threads racing to configure the library end up with the same one.

Returns:

  • (Configuration) —

    the current configuration, built with defaults if the library has not been configured yet



238
239
240
241
242
 
# File 'lib/horologium/configuration.rb', line 238

def configuration
  @configuration || CONFIGURATION_LOCK.synchronize do
    @configuration ||= Configuration.new
  end
end

.configure {|config| ... } ⇒ Configuration

Configures the library. The yielded configuration is frozen when the block returns, so it can be set once at boot and not changed again. It is frozen even when the block raises, so a configuration that failed half way through cannot be quietly finished off later.

It is called once. A second call finds the configuration already frozen and raises ConfigurationError, so set everything in one block.

Examples:

Horologium.configure do |c|
  c.default_precision = :exact
end

Yield Parameters:

Returns:



223
224
225
226
227
228
229
230
231
 
# File 'lib/horologium/configuration.rb', line 223

def configure
  config = configuration
  begin
    yield config if block_given?
  ensure
    config.freeze
  end
  config
end

.current_precision ⇒ Symbol

The precision in effect right now: the one set by with_precision if a scope is open, otherwise the default. This is what a constructor consults when it is not given a precision of its own.

Returns:

  • (Symbol) —

    :standard or :exact



254
255
256
 
# File 'lib/horologium/configuration.rb', line 254

def current_precision
  Thread.current[:horologium_current_precision] || default_precision
end

.default_precision ⇒ Symbol

Returns the configured default precision.

Returns:

  • (Symbol) —

    the configured default precision



245
246
247
 
# File 'lib/horologium/configuration.rb', line 245

def default_precision
  configuration.default_precision
end

.reset_configuration! ⇒ void

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.

This method returns an undefined value.

Clears the configuration and any open precision scope. Meant for test isolation, so one test's configuration does not carry into another.



286
287
288
289
 
# File 'lib/horologium/configuration.rb', line 286

def reset_configuration!
  @configuration = nil
  Thread.current[:horologium_current_precision] = nil
end

.with_precision(precision) ⇒ Object

Runs the block with a chosen precision in effect, then restores whatever was in effect before. The scope is per-fiber, so it is safe to use in a threaded or fibered context and cannot leak into other work. It does not touch the frozen default.

Examples:

Horologium.with_precision(:exact) do
  # instants built here default to :exact
end

Parameters:

  • precision (Symbol) —

    :standard or :exact

Returns:

  • (Object) —

    the block's return value

Raises:



270
271
272
273
274
275
276
277
278
279
 
# File 'lib/horologium/configuration.rb', line 270

def with_precision(precision)
  Numeric::Precision.validate!(precision)
  previous = Thread.current[:horologium_current_precision]
  Thread.current[:horologium_current_precision] = precision
  begin
    yield
  ensure
    Thread.current[:horologium_current_precision] = previous
  end
end