marsdate 1.1.3 → 2.0.0

data/lib/marsdate.rb

@@ -1,328 +1,376 @@
 require 'date'
+require 'json'
+require_relative 'marsdate/version'
+require_relative 'marsdate/timescale'
+require_relative 'marsdate/calendar'
 
 class MarsDateTime
 
-  VERSION = "1.1.3"
-
   include Comparable
 
-  MSEC_PER_SOL   = 88775244 # .09   # Really + 0.09
-  SOLS_PER_MYEAR = 668.5921
-  MSEC_PER_DAY   = 86400000
-
-  FAKE_MSEC_PER_MYEAR = (668*MSEC_PER_SOL)
-
-  TimeStretch    = MSEC_PER_SOL/MSEC_PER_DAY.to_f
-
   Months = %w[ UNDEFINED
                M-January   Gemini      M-February Cancer
-               M-March     Leo         M-April    Virgo 
-               M-May       Libra       M-June     Scorpio 
-               M-July      Sagittarius M-August   Capricorn 
-               M-September Aquarius    M-October  Pisces 
-               M-November  Aries       M-December Taurus ]   
+               M-March     Leo         M-April    Virgo
+               M-May       Libra       M-June     Scorpio
+               M-July      Sagittarius M-August   Capricorn
+               M-September Aquarius    M-October  Pisces
+               M-November  Aries       M-December Taurus ]
                # no month 0
 
-  Week   = %w[ Sunday Monday Tuesday Wednesday Thursday Friday Saturday ]
+  Week = %w[ Sunday Monday Tuesday Wednesday Thursday Friday Saturday ]
 
-  EpochMCE  = DateTime.new(1,1,21)
-  EpochCE   = DateTime.new(1,1,1)
-  JulianDay1 = 1721445   # Jan 1, 1 AD
+  EPOCH_MSD = Calendar::EPOCH_MSD
+  SOL_DAYS = TimeScale::SOL_DAYS
+  SOL_SI_SECONDS = TimeScale::SOL_SI_SECONDS
+  SOLS_PER_MYEAR = Calendar::MEAN_YEAR
 
+  attr_reader :msd
   attr_reader :year, :month, :sol, :epoch_sol, :year_sol
-  attr_reader :shr, :smin, :ssec    # stretched time
-  attr_reader :mems
-
   attr_reader :dow, :day_of_week
-  attr_reader :mhrs, :mmin, :msec
+  attr_reader :mtc_hour, :mtc_min, :mtc_sec
+  attr_reader :mxt_hour, :mxt_min, :mxt_sec
 
   alias myear year
-  alias hr   mhrs
-  alias min  mmin
-  alias sec  msec
+  alias day  sol
+
+  # Named-clock readout of one instant. MarsDateTime.mxt(...) constructs;
+  # md.mxt reads. Date fields are the parent's; %H/%M/%S are this clock.
+  class ClockView
+    attr_reader :scale
+
+    def initialize(parent, scale)
+      @parent = parent
+      @scale = scale
+    end
+
+    def hour
+      @scale == :mxt ? @parent.mxt_hour : @parent.mtc_hour
+    end
+
+    def min
+      @scale == :mxt ? @parent.mxt_min : @parent.mtc_min
+    end
 
-  def self.leap?(myear)    # class method for convenience
-    return (myear % 2 == 1) if (myear % 10 != 0)
-    return true if (myear % 1000 == 0)
-    return false if (myear % 100 == 0)
-    return true
+    def sec
+      @scale == :mxt ? @parent.mxt_sec : @parent.mtc_sec
+    end
+
+    def year;        @parent.year;        end
+    def month;       @parent.month;       end
+    def sol;         @parent.sol;         end
+    def day_of_week; @parent.day_of_week; end
+    def month_name;  @parent.month_name;  end
+    def dow;         @parent.dow;         end
+    def year_sol;    @parent.year_sol;    end
+    def epoch_sol;   @parent.epoch_sol;   end
+    def msd;         @parent.msd;         end
+    def earth_date;  @parent.earth_date;  end
+
+    def to_s
+      TimeScale.format_hms(hour, min, sec)
+    end
+
+    def inspect
+      "#<#{@scale.to_s.upcase} #{self}>"
+    end
+
+    # Specifier list inspired by Time#strftime. %H/%M/%S/%X are this clock;
+    # %Z is the clock name (MXT or MTC), not a timezone.
+    def format(fmt)
+      @parent.send(:format_with, fmt, hour, min, sec, @scale.to_s.upcase)
+    end
+  end
+
+  def self.leap?(myear)
+    Calendar.leap?(myear)
   end
 
-  def self.short?(myear)  # short year
+  def self.short?(myear)
     !leap?(myear)
   end
 
-  def self.long?(myear)  # long year
+  def self.long?(myear)
     leap?(myear)
   end
 
   def self.sols_in_month(m, year)
-    return 28 if m < 24
-    return 25 if leap?(year)
-    return 24
+    Calendar.sols_in_month(m, year)
+  end
+
+  def self.from_msd(msd)
+    at(msd)
+  end
+
+  def self.at(msd)
+    obj = allocate
+    obj.send(:init_from_msd, msd)
+    obj
+  end
+
+  def self.mxt(year, month, sol, hour = 0, min = 0, sec = 0)
+    civil(year, month, sol, hour, min, sec, :mxt)
+  end
+
+  def self.mtc(year, month, sol, hour = 0, min = 0, sec = 0)
+    civil(year, month, sol, hour, min, sec, :mtc)
   end
 
   def self.now
-    d = DateTime.now
-    MarsDateTime.new(d)
+    new(DateTime.now)
   end
 
+  # Current MCE sol at 00:00 (MXT = MTC midnight). Not Earth Date.today.
   def self.today
-    d = DateTime.now
-    MarsDateTime.new(d)
+    n = now
+    mxt(n.year, n.month, n.sol)
   end
 
-  def leaps(myr)
-    n = 0
-    1.upto(myr) {|i| n+=1 if MarsDateTime.leap?(i) } 
-    n
+  # Earth caption of 1/1/1 00:00 and of Ls=0 on that sol.
+  # Times treat JD_TT as UT (no year-1 ΔT). See TimeScale.epoch_report.
+  def self.epoch_caption
+    TimeScale.epoch_report
   end
 
-  def to_yaml_properties
-    %w[@myear @month @sol @epoch_sol @year_sol @dow @day_of_week @msme @mhrs @mmin @msec]
+  def self.from_json(str)
+    hash = JSON.parse(str)
+    msd = hash['msd'] || hash[:msd]
+    raise ArgumentError, 'JSON must include msd' if msd.nil?
+    from_msd(msd)
   end
 
-  def inspect
-    time = ('%02d' % @mhrs) + ":" + ('%02d' % @mmin) + ":" + ('%02d' % @msec)
-    "#@year/#{'%02d' % @month}/#{'%02d' % @sol} " + 
-    "(#@year_sol, #@epoch_sol) #@day_of_week " +
-    time
+  def initialize(*params)
+    n = params.size
+    case n
+    when 3..6
+      init_yms(*params, clock: :mxt)
+    when 0
+      init_from_msd(TimeScale.msd(DateTime.now))
+    when 1
+      case params.first
+      when Integer, Float
+        init_from_msd(params.first)
+      when Date, DateTime
+        init_from_msd(TimeScale.msd(params.first))
+      else
+        raise ArgumentError, "Expected MSD, Date, or DateTime (got #{params.first.class})"
+      end
+    else
+      raise ArgumentError, "Bad params: #{params.inspect}"
+    end
   end
 
-  def to_s
-    time = self.strftime('%H:%M:%S [%P:%Q:%R]')
-    "#@day_of_week, #{Months[@month]} #@sol, #@year at #{time}"
+  def mxt
+    ClockView.new(self, :mxt)
   end
 
-  def leap?
-    MarsDateTime.leap?(@year)    # DRY
+  def mtc
+    ClockView.new(self, :mtc)
   end
 
-  def short?
-    ! leap?
+  def as_json(_options = {})
+    { msd: @msd,
+      year: @year,
+      month: @month,
+      sol: @sol,
+      epoch_sol: @epoch_sol,
+      year_sol: @year_sol,
+      dow: @dow,
+      day_of_week: @day_of_week,
+      mtc: format_mtc,
+      mxt: format_mxt }
   end
 
-  def long?
-    leap?
+  def to_json(*options)
+    as_json.to_json(*options)
   end
 
-  def month_name
-    Months[@month]
+  def to_yaml_properties
+    %w[@msd]
+  end
+
+  def inspect
+    sprintf('%d/%02d/%02d (%d, %d) %s MXT %s MTC %s MSD %.8f',
+            @year, @month, @sol, @year_sol, @epoch_sol, @day_of_week,
+            format_mxt, format_mtc, @msd)
   end
 
-  ###########
+  def to_s
+    "#{@day_of_week}, #{month_name} #{@sol}, #{@year} at MXT #{format_mxt} / MTC #{format_mtc}"
+  end
 
-  def initialize(*params)
-    n = params.size
-    case n
-      when 3..6
-        init_yms(*params)
-      when 0
-        init_datetime(DateTime.now)
-      when 1
-        case params.first
-          when Integer, Float
-            init_mems(params.first)
-          when Date
-            init_date(params.first)
-          when DateTime
-            init_datetime(params.first)
-        else
-          raise "Expected number or DateTime" 
-        end
-      else
-        raise "Bad params: #{params.inspect}"
-    end
-    compute_stretched
-  end
-
-  def check_ymshms(my, mm, msol, mhr=0, mmin=0, msec=0)
-    text = ""
-    text << "year #{my} is not an integer\n" unless my.is_a? Integer
-    text << "month #{mm} is out of range" unless (1..24).include? mm
-    text << "sol #{msol} is out of range" unless (1..28).include? msol
-    text << "hour #{mhr} is out of range" unless (0..24).include? mhr
-    text << "minute #{mmin} is out of range" unless (0..59).include? mmin
-    text << "second #{msec} is out of range" unless (0..59).include? msec
-    if !MarsDateTime.leap?(my) && mm == 24 && msol > 24
-      text << "sol #{msol} is invalid in a non-leap year" 
-    end
-    raise text unless text.empty?
-  end
-
-  def init_yms(my, mm, msol, mhr=0, mmin=0, msec=0)
-    check_ymshms(my, mm, msol, mhr, mmin, msec)
-    zsol = msol - 1  # z means zero-based
-    zmy  = my - 1    # my means Martian year
-    zesol = zmy*668 + leaps(my-1) + (mm-1)*28 + zsol
-#   @mems is "Martian (time since) epoch in milliseconds"
-    @mems = zesol*MSEC_PER_SOL + (mhr*3600 + mmin*60 + msec)*1000
-    @year, @month, @sol, @mhrs, @mmin, @msec = my, mm, msol, mhr, mmin, msec
-    @epoch_sol = zesol + 1
-    @dow = (@epoch_sol-1) % 7
-    @day_of_week = Week[@dow]
-    @year_sol  = (mm-1)*28 + msol
-  end
-
-  def compute_stretched
-    # Handle stretched time...
-    sec = @mhrs*3600 + @mmin*60 + @msec
-    sec /= TimeStretch
-    @shr,  sec = sec.divmod(3600)
-    @smin, sec = sec.divmod(60)
-    @ssec = sec.round
-  end
-
-  def init_mems(mems)
-    # Note: The sol length is off by 0.09 msec -- to properly fix this 
-    # will require measuring in microseconds so as to avoid floating-point math.
-    # The "round" calls below were experimental and were "mostly" successful.
-    full_years = 0
-    loop do
-      millisec = FAKE_MSEC_PER_MYEAR
-      millisec += MSEC_PER_SOL if MarsDateTime.leap?(full_years+1)
-      break if mems < millisec
-      mems -= millisec
-      # puts "Subtracting #{millisec} -- one full year => #{mems}"
-      full_years += 1
-    end
+  def format_mtc(fmt = nil)
+    fmt ? format_with(fmt, @mtc_hour, @mtc_min, @mtc_sec, 'MTC') : mtc.to_s
+  end
 
-    mspm = MSEC_PER_SOL*28
-    full_months,mems = mems.divmod(mspm)
-    full_days, mems  = mems.divmod(MSEC_PER_SOL)
-    full_hrs, mems   = mems.divmod(3_600_000)
-    full_min, mems   = mems.divmod(60_000)
+  def format_mxt(fmt = nil)
+    fmt ? format_with(fmt, @mxt_hour, @mxt_min, @mxt_sec, 'MXT') : mxt.to_s
+  end
 
-    sec = mems/1000.0
-    my = full_years  + 1  # 1-based
-    mm = full_months + 1
-    ms = full_days   + 1
-    mhr = full_hrs        # 0-based
-    mmin = full_min
-    msec = sec.to_i
-    frac = sec - msec     # fraction of a sec
+  def leap?
+    MarsDateTime.leap?(@year)
+  end
 
-    init_yms(my, mm, ms, mhr, mmin, msec)
+  def short?
+    !leap?
   end
 
-  def init_date(date)
-    dt = date.to_datetime
-    days = dt.jd - JulianDay1
-    secs = days*86400 + dt.hour*3600 + dt.min*60 + dt.sec
-    init_mems(secs*1000)
+  def long?
+    leap?
   end
 
-  def init_datetime(dt)
-    days = dt.jd - JulianDay1
-    secs = days*86400 + dt.hour*3600 + dt.min*60 + dt.sec
-    init_mems(secs*1000)
+  def month_name
+    Months[@month]
   end
 
   def ymshms
-    [@year, @month, @sol, @mhrs, @mmin, @msec]
+    [@year, @month, @sol, @mxt_hour, @mxt_min, @mxt_sec.to_i]
   end
 
-  def -(other)  # FIXME? sols or secs?
+  def -(other)
     case other
-      when MarsDateTime
-        diff = @mems - other.mems
-        diff.to_f / MSEC_PER_SOL
-      when DateTime
-        other = MarsDateTime.new(other)
-        diff = @mems - other.mems
-        diff.to_f / MSEC_PER_SOL
-      when Integer, Float
-        self + (-other)
+    when MarsDateTime
+      @msd - other.msd
+    when Date, DateTime
+      @msd - MarsDateTime.new(other).msd
+    when Integer, Float
+      self + (-other)
     else
-      raise "Unexpected data type"
+      raise ArgumentError, "Unexpected data type #{other.class}"
     end
   end
 
-  def +(sols)  # FIXME? sols or secs?
-    millisec = sols * MSEC_PER_SOL
-    MarsDateTime.new(@mems + millisec)
+  def +(sols)
+    MarsDateTime.at(@msd + sols.to_f)
   end
 
   def <=>(other)
     case other
-      when MarsDateTime
-        @mems <=> other.mems
-      when DateTime
-        @mems <=> MarsDateTime.new(other).mems
+    when MarsDateTime
+      @msd <=> other.msd
+    when Date, DateTime
+      @msd <=> MarsDateTime.new(other).msd
     else
-      raise "Invalid comparison"
+      raise ArgumentError, "Invalid comparison with #{other.class}"
     end
   end
 
   def earth_date
-    secs = @mems/1000
-    days,secs = secs.divmod(86400)
-    hrs, secs = secs.divmod(3600)
-    min, secs = secs.divmod(60)
-    jday = days + JulianDay1
-    DateTime.jd(jday, hrs, min, secs)
-  end
-
-  def strftime(fmt)
-    str = fmt.dup
-    pieces = str.scan(/(%.|[^%]+)/).flatten
-    final = ""
+    TimeScale.earth_from_msd(@msd)
+  end
+
+  # Date tokens plus MXT for %H/%M/%S/%X. Specifier list inspired by
+  # Time#strftime. Same as format_mxt(fmt). MTC: format_mtc(fmt) or md.mtc.format.
+  def format(fmt)
+    format_mxt(fmt)
+  end
+
+  def self.civil(year, month, sol, hour, min, sec, clock)
+    obj = allocate
+    obj.send(:init_yms, year, month, sol, hour, min, sec, clock: clock)
+    obj
+  end
+  private_class_method :civil
+
+  def format_with(fmt, hour, min, sec, clock)
+    pieces = fmt.to_s.scan(/(%%|%.|%|[^%]+)/).flatten
+    final = ''
     zmonth = '%02d' % @month
     zsol = '%02d' % @sol
-    zhh = '%02d' % @mhrs  # stretched
-    zmm = '%02d' % @mmin
-    zss = '%02d' % @msec
-    zhc = '%02d' % @shr   # canonical
-    zmc = '%02d' % @smin
-    zsc = '%02d' % @ssec
-   
+    zhh = '%02d' % hour
+    zmm = '%02d' % min
+    zss = '%02d' % sec.to_i
+
     pieces.each do |piece|
       case piece
-        when "%a"; final << @day_of_week[0..2]
-        when "%A"; final << @day_of_week
-        when "%b"; final << (@month.odd? ? month_name[2..4] : month_name[0..2])
-        when "%B"; final << month_name
-        when "%d"; final << zsol
-        when "%e"; final << ('%2d' % @sol)
-        when "%F"; final << "#@year-#{zmonth}-#{zsol}"
-        when "%H"; final << zhh
-        when "%j"; final << @year_sol.to_s
-        when "%m"; final << zmonth  # @month.to_s
-        when "%M"; final << zmm
-        when "%s"; final << @msec.to_s  # was: (@mems*1000).to_i.to_s
-        when "%S"; final << zss
-        when "%u"; final << (@dow + 1).to_s
-        when "%U"; final << (@year_sol/7 + 1).to_s
-        when "%w"; final << @dow.to_s
-        when "%x"; final << "#@year/#{zmonth}/#{zsol}"
-        when "%X"; final << "#{zhh}:#{zmm}:#{zss}"
-        when "%Y"; final << @year.to_s
-        when "%n"; final << "\n"
-        when "%t"; final << "\t"
-        when "%%"; final << "%"
-        when "%P"; final << ("%02d" % @shr)
-        when "%Q"; final << ("%02d" % @smin)
-        when "%R"; final << ("%02d" % @ssec)
-        else
-          final << piece
+      when '%a'; final << @day_of_week[0..2]
+      when '%A'; final << @day_of_week
+      when '%b'; final << (@month.odd? ? month_name[2..4] : month_name[0..2])
+      when '%B'; final << month_name
+      when '%d'; final << zsol
+      when '%e'; final << ('%2d' % @sol)
+      when '%F'; final << "#{@year}-#{zmonth}-#{zsol}"
+      when '%H'; final << zhh
+      when '%j'; final << @year_sol.to_s
+      when '%m'; final << zmonth
+      when '%M'; final << zmm
+      when '%s'; final << sec.to_i.to_s
+      when '%S'; final << zss
+      when '%u'; final << (@dow + 1).to_s
+      when '%U'; final << (@year_sol / 7 + 1).to_s
+      when '%w'; final << @dow.to_s
+      when '%x'; final << "#{@year}/#{zmonth}/#{zsol}"
+      when '%X'; final << "#{zhh}:#{zmm}:#{zss}"
+      when '%Y'; final << @year.to_s
+      when '%Z'; final << clock
+      when '%n'; final << "\n"
+      when '%t'; final << "\t"
+      when '%%'; final << '%'
+      else
+        final << piece
       end
     end
     final
   end
-  
-=begin
-    *  %I - Hour of the day, 12-hour clock (01..12)
-    *  %p - Meridian indicator (``AM''  or  ``PM'')
-       %U - Week  number  of the current year,
-               starting with the first Sunday as the first
-               day of the first week (00..53)
-       %W - Week  number  of the current year,
-               starting with the first Monday as the first
-               day of the first week (00..53)
-    *  %y - Year without a century (00..99)
-       %Z - Time zone name
-
-=end
+  private :format_with
 
-end
+  private
+
+  def init_yms(my, mm, msol, mhr = 0, mmin = 0, msec = 0, clock: :mxt)
+    Calendar.check_ymd!(my, mm, msol)
+    check_hms!(mhr, mmin, msec, clock)
+    frac = frac_from_hms(mhr, mmin, msec, clock)
+    init_from_msd(Calendar.msd_at(my, mm, msol, frac))
+  end
+
+  def init_from_msd(msd)
+    @msd = msd.to_f
+    index = @msd.floor - EPOCH_MSD
+    if index < 0
+      raise ArgumentError, "MSD #{@msd} is before MCE 1/1/1 (EPOCH_MSD=#{EPOCH_MSD})"
+    end
+    @year, @month, @sol = Calendar.ymd_from_msd(@msd)
+    @epoch_sol = Calendar.sol_index(@year, @month, @sol) + 1
+    @year_sol = (@month - 1) * 28 + @sol
+    @dow = Calendar.dow(@year, @month, @sol)
+    @day_of_week = Week[@dow]
+    frac = TimeScale.sol_fraction_of(@msd)
+    @mtc_hour, @mtc_min, @mtc_sec = TimeScale.hours_to_hms(
+      frac * 24.0, limit: 24
+    )
+    @mxt_hour, @mxt_min, @mxt_sec = TimeScale.hours_to_hms(
+      frac * SOL_SI_SECONDS / 3600.0
+    )
+  end
+
+  def check_hms!(h, min, sec, clock)
+    unless h.is_a?(Numeric) && min.is_a?(Numeric) && sec.is_a?(Numeric)
+      raise ArgumentError, 'hour/minute/second must be numeric'
+    end
+    unless min >= 0 && min < 60 && sec >= 0 && sec < 60
+      raise ArgumentError, "minute/second out of range (#{min}:#{sec})"
+    end
+    case clock.to_sym
+    when :mtc
+      hours = h.to_f + min.to_f / 60.0 + sec.to_f / 3600.0
+      unless hours >= 0.0 && hours < 24.0
+        raise ArgumentError, "MTC #{h}:#{min}:#{sec} is outside [00:00:00, 24:00:00)"
+      end
+    when :mxt
+      si = h.to_f * 3600.0 + min.to_f * 60.0 + sec.to_f
+      unless si >= 0.0 && si < SOL_SI_SECONDS
+        raise ArgumentError, "MXT #{h}:#{min}:#{sec} is outside one sol"
+      end
+    else
+      raise ArgumentError, "clock must be :mtc or :mxt (got #{clock.inspect})"
+    end
+  end
 
+  def frac_from_hms(h, min, sec, clock)
+    case clock.to_sym
+    when :mtc
+      (h.to_f + min.to_f / 60.0 + sec.to_f / 3600.0) / 24.0
+    when :mxt
+      (h.to_f * 3600.0 + min.to_f * 60.0 + sec.to_f) / SOL_SI_SECONDS
+    end
+  end
+end

data/marsdate.gemspec

@@ -0,0 +1,31 @@
+require_relative 'lib/marsdate/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'marsdate'
+  s.version     = MarsDateTime::VERSION
+  s.license     = 'MIT'
+  s.summary     = 'Date/time library for Mars'
+  s.description = <<-EOS
+                  This is a library for handling dates and times on Mars
+                  for the Martian Common Era calendar (created by Hal Fulton).
+                  The functionality closely follows that of Ruby's Time class.
+                  EOS
+  s.authors     = ['Hal Fulton']
+  s.email       = 'rubyhacker@gmail.com'
+  s.files       = Dir['lib/**/*.rb', 'bin/*', 'test/**/*.rb'] +
+                  %w[CHANGELOG.md LICENSE.txt README.md marsdate.gemspec]
+  s.bindir      = 'bin'
+  s.executables = ['marsdate']
+  s.require_paths = ['lib']
+  s.required_ruby_version = '>= 2.7'
+  s.homepage    = 'https://github.com/Hal9000/marsdate'
+  s.metadata    = {
+    'bug_tracker_uri' => "#{s.homepage}/issues",
+    'changelog_uri' => "#{s.homepage}/blob/master/CHANGELOG.md",
+    'source_code_uri' => s.homepage
+  }
+  s.add_development_dependency 'minitest', '~> 6.0'
+  s.add_development_dependency 'rake', '~> 13.4'
+  s.post_install_message = "\n Success! Run executable 'marsdate' for help.\n "
+end
+