wtf 0.0.1

data/CHANGELOG

@@ -0,0 +1,2 @@
+0.0.1 (November 29, 2009)
+* Initial release.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2009 Wyatt M. Greene
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,17 @@
+= World Time Format Converter
+
+== Description
+
+The WTF gem provides a Ruby class to convert between standard
+time and World Time Format.  For more information, visit
+http://www.worldtimeformat.com
+
+== Examples
+
+  WTF::Date.new("FIWIT:NAAAA").as_utc  # converts a WTF datetime to a Ruby Time object
+  WTF::Date.new(time).as_wtf           # converts from a Ruby Time object to a WTF string
+  WTF::Date.now.as_wtf                 # returns a WTF string representing the current datetime
+  WTF::Date.now.date_part              # returns a WTF string representing the current date
+  WTF::Date.now.time_part              # returns a WTF string representing the current time
+  WTF::Date.convert("FIWIT:NAAAA")     # convenience method for converting
+  WTF::Date.convert(time)              # convenience method for converting

data/Rakefile

@@ -0,0 +1,48 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+ 
+desc 'Default: run unit tests.'
+task :default => :test
+ 
+desc 'Test WTF.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+ 
+desc 'Generate documentation for WTF.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'WTF'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name          = "wtf"
+    s.version       = "0.0.1"
+    s.author        = "Wyatt Greene"
+    s.email         = "techiferous@gmail.com"
+    s.summary       = "Converts between World Time Format and standard dates and times."
+    s.description   = %Q{
+      The WTF gem provides a Ruby class to convert between standard
+      time and World Time Format.  For more information, visit
+      http://www.worldtimeformat.com
+    }
+    s.require_path  = "lib"
+    s.files         = ["lib/wtf.rb", "LICENSE", "Rakefile", "README",
+                       "CHANGELOG",
+                       "test/wtf_test.rb", "test/test_helper.rb"]
+    s.homepage      = "http://github.com/techiferous/wtf"
+    s.requirements  << "none"
+    s.has_rdoc      = true
+    s.test_files    = Dir.glob("test/**/*.rb")
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end

data/lib/wtf.rb

@@ -0,0 +1,288 @@
+require 'date'
+
+module WTF
+  class Date
+    
+    # creates a new WTF::Date object.  The argument can be a string representing the
+    # date and/or time in World Time Format, or it can be a Time object.  If the
+    # argument is missing, Time.now is assumed.
+    #
+    # Examples:
+    #
+    #   WTF::Date.new(":NB")     #=> returns a new WTF::Date object for the WTF time :NB
+    #   WTF::Date.new(":RJA")    #=> returns a new WTF::Date object for the WTF date :RJA
+    #   WTF::Date.new("MM:BRT")  #=> returns a new WTF::Date object for the WTF datetime MM:BRT
+    #   WTF::Date.new            #=> returns a new WTF::Date object corresponding to right now
+    #   WTF::Date.new(Time.utc(2010, 5, 6))  #=> returns a new WTF::Date object for the given Time
+    #
+    # If the argument is in World Time Format, it must can contain a date part,
+    # a time part, and a colon to separate them.  Here are some examples of valid formats:
+    #
+    # - "FJKRM:BROMQ" -- This is a fully specified World Time Format date and
+    #   time.  The first part is the date part and the second part is the time
+    #   part.  The date part cannot be longer than five characters.  The time
+    #   part can be longer than five characters, but any characters after
+    #   the fifth character are ignored when calculating.
+    # - ":BROMQ" -- You can leave out the date part.  Today is assumed.
+    # - "FJKRM:" -- You can leave out the time part.  The beginning of the
+    #   Julian day is assumed (which is noon).
+    # - "BROMQ" -- If you leave out the colon, it is assumed that you are
+    #   giving the time, not the date.
+    # - "RM:BROMQ" -- You can leave out some of the digits for the date.  If
+    #   you do, the remaining digits will be filled in according to today's
+    #   date.  If today's date is FMBAZ, then "RM:BROMQ" becomes
+    #   "FMBRM:BROMQ".
+    # - ":BR" -- You don't have to specify all five of the time digits.
+    # - "A:B" -- This is a valid format.
+    #
+    # Also note:
+    #
+    # - The date conversion does not work before the Gregorian calendar change
+    #   that happened in October 1582.
+    # - Since the date part is limited to five characters, there is an upper
+    #   bound for how far into the future you can do a date conversion.
+    # - The time part is limited to five characters and therefore the
+    #   time precision is limited to about 10 milliseconds.
+    # - Leap seconds were not taken into account.
+    #
+    def initialize(time = nil)
+      if time
+        if time.is_a? String
+          @time = convert_from_wtf(time)
+        elsif time.is_a? Time
+          @time = time
+        else
+          raise ArgumentError.new("Argument must be a String or a Time.")
+        end
+      else
+        @time = ::Time.now
+      end
+      @wtf = convert_to_wtf(@time)
+    end
+    
+    # now is a synonym for WTF::Date.new.  It returns a WTF::Date object initialized with
+    # the current date and time.
+    #
+    def self.now
+      self.new
+    end
+
+    # convert is a convenience method to make it easier to convert between WTF
+    # times and standard times.
+    #    
+    # Examples:
+    # 
+    #   WTF::Date.convert("FIWIT:NAAAA")  #=> same as WTF::Date.new("FIWIT:NAAAA").as_utc
+    #   WTF::Date.convert(time)           #=> same as WTF::Date.new(time).as_wtf
+    #
+    def self.convert(arg)
+      return nil if arg.nil?
+      return self.new(arg).as_utc if arg.is_a?(String)
+      return self.new(arg).as_wtf if arg.is_a?(Time)
+      raise ArgumentError.new("Argument must be a String or a Time.")
+    end
+    
+    # returns a Time object representing the WTF::Date's date and time in UTC.
+    #
+    # Examples:
+    #
+    #   standard_time = WTF::Date.new("FIWIT:NAAAA").as_utc
+    #   standard_time = WTF::Date.new(":BJR").as_utc
+    #   standard_time = WTF::Date.new("XQ:ARM").as_utc
+    #
+    def as_utc
+      @time
+    end
+    
+    # returns a string representing the date and time in World Time Format.
+    #
+    # Example:
+    #
+    #   wtf_date = WTF::Date.new(Time.utc(2002, 7, 10, 13, 55, 1, 777000))
+    #   wtf_date.as_wtf  #=> "FJNXQ:CCAAA"
+    #
+    def as_wtf
+      @wtf
+    end
+
+    # returns just the World Time Format date.
+    #
+    # Example:
+    #
+    #   wtf_date = WTF::Date.new(Time.utc(2002, 7, 10, 13, 55, 1, 777000))
+    #   wtf_date.date_part  #=> "FJNXQ"
+    #
+    def date_part
+      @wtf =~ /^([A-Z]{0,5}):([A-Z]*)$/
+      $1
+    end
+
+    # returns just the World Time Format time.
+    #
+    # Example:
+    #
+    #   wtf_date = WTF::Date.new(Time.utc(2002, 7, 10, 13, 55, 1, 777000))
+    #   wtf_date.time_part  #=> "CCAAA"
+    #
+    def time_part
+      @wtf =~ /^([A-Z]{0,5}):([A-Z]*)$/
+      $2
+    end
+
+    #--------------------#
+    #   PRIVATE METHODS  #
+    #++
+
+    private
+    
+    SECONDS_IN_A_DAY = 86400
+    MILLIS_IN_A_DAY = SECONDS_IN_A_DAY * 1000  # millis means milliseconds
+
+    def convert_from_wtf(wtf)
+
+      raise ArgumentError.new("Argument is empty.") if wtf.nil? || wtf.empty?
+
+      # If no colon is given, we assume we have a time, not a date.
+      if !wtf.include?(":")
+        wtf = ":" + wtf
+      end
+
+      if wtf !~ /^([A-Z]{0,5}):([A-Z]*)$/
+        raise ArgumentError.new("Time format error")
+      end
+      wtf_date = $1
+      wtf_time = $2
+      
+      # we need to fill in ambiguous dates.  If today is FJSTR: and the given
+      # date is BM:, we fill in the blanks according to today's date
+      # like so: FJSBM:
+      if wtf_date.length < 5
+        reference_date = self.class.now.date_part
+        wtf_date = reference_date[0, 5-wtf_date.length] + wtf_date
+      end
+      
+      # we don't care about anything more precise than 5 time digits
+      if wtf_time.length > 5
+        wtf_time = wtf_time[0, 5]
+      end
+
+      julian_date = 0
+      # compute integer part of Julian Date
+      for i in (0..4) do
+        julian_date += (wtf_date[i]-65) * (26**(4-i))
+      end
+      # compute fractional part of Julian Date
+      fractional = 0
+      for i in (0..(wtf_time.length-1)) do
+        fractional += (wtf_time[i]-65) / (26**(i+1)).to_f
+      end
+      
+      # adjust for the astronomical Julian day, which starts at noon
+      if fractional >= 0.5
+        fractional -= 0.5
+        julian_date += 1
+      else
+        fractional += 0.5
+      end
+
+      date = ::Date.jd(julian_date+fractional)
+      
+      # Normally I love Ruby and how it gets out of my way, but this is
+      # absolutely ridiculous.  I expect to be able to create a Date object,
+      # initialize it with the Julian Day, then simply call to_time.
+      # Why Ruby doesn't provide a to_time method, I don't know.  So I'm resorting
+      # to calling private (!) methods on the Date class.  Shame on Ruby
+      # and shame on me! :)
+      fraction_of_seconds = date.send(:sec_fraction) * SECONDS_IN_A_DAY
+      microseconds = fraction_of_seconds * 1000000
+      utc_time = ::Time.utc(date.year,
+                            date.month,
+                            date.day,
+                            date.send(:hour),
+                            date.send(:min),
+                            date.send(:sec),
+                            microseconds)
+
+      utc_time.getlocal
+
+    end
+    
+    def convert_to_wtf(time)      
+      utc = time.utc
+      date = ::Date.civil(utc.year, utc.month, utc.day)
+      julian_day = date.jd.to_i
+      # adjust for the astronomical Julian day, which starts at noon
+      if utc.hour >= 12
+        hour = utc.hour - 12
+      else
+        hour = utc.hour + 12
+        julian_day -= 1
+      end
+      fractional = hour * 3600 + utc.min * 60 + utc.sec + (utc.usec / 1000000.0)
+      date_part = self.class.send(:decimal_to_alphabase, julian_day)
+      time_part = self.class.send(:time_to_wtf, fractional*1000)
+      date_part + ':' + time_part
+    end
+    
+    # Given a number in base 10, return a number in alphabase.  Note that
+    # alphabase is different than base 26.  Base 26 uses digits within the range
+    # 0-9,a-p.  Alphabase is also based on a radix of 26, but uses digits within
+    # the range A-Z.
+    # 
+    # To simplify the algorithm, this function does not accept real numbers as
+    # input, only integers.
+    # 
+    def self.decimal_to_alphabase(decimal)
+      if (decimal.floor != decimal)
+        raise ArgumentError.new("Floats are not supported.")
+      end
+      alphabase = ""
+      base26 = decimal.to_s(26)
+      for i in (0..(base26.length-1))
+        c = base26[i]
+        if (c == 45) # hyphen for negative numbers
+          alphabase += "-"
+        elsif ((c >= 97) && (c <= 112)) # lower case a-p -> K-Z
+          alphabase += (c-22).chr
+        elsif ((c >= 48) && (c <= 57)) # number 0-9 -> A-J
+          alphabase += (c+17).chr
+        else
+          raise "Unexpected character."
+        end
+      end
+      alphabase
+    end
+    private_class_method :decimal_to_alphabase
+    
+    # Given an integer representing the number of milliseconds into the Julian
+    # day, return a five-character string representing the time in World Time
+    # Format.
+    #
+    def self.time_to_wtf(millis_into_the_day)
+      if (millis_into_the_day < 0)
+        raise ArgumentError.new("Negative values are not supported.")
+      end
+      if (millis_into_the_day >= MILLIS_IN_A_DAY)
+        message = "Value (#{millis_into_the_day}) must be smaller than"
+        message << " the number of milliseconds in a day (#{MILLIS_IN_A_DAY})."
+        raise ArgumentError.new(message)
+      end
+      result = ""
+      # For the first loop iteration, the unit represents the number of
+      # milliseconds in an entire day.  Then it represents the number of
+      # milliseconds in an alphabetic hour, then in an alphabetic minute, all
+      # the way down to the number of milliseconds in an alphabetic subsubsecond.
+      unit = MILLIS_IN_A_DAY
+      remainder = millis_into_the_day  # milliseconds left to process
+      5.times do
+        unit /= 26.0
+        num_units = (remainder.floor / unit).to_i
+        remainder -= (num_units * unit)
+        result += (num_units.to_i+65).chr
+      end
+      result
+    end
+    private_class_method :time_to_wtf
+    
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,3 @@
+require 'test/unit'
+require 'rubygems'
+require 'redgreen'

data/test/wtf_test.rb

@@ -0,0 +1,138 @@
+require 'test/test_helper'
+require 'wtf'
+
+class WtfTest < Test::Unit::TestCase
+
+  #--------------------------#
+  # Testing private methods. #
+  #--------------------------#
+  
+  def test_alphabase_conversion_with_whole_numbers
+    assert_equal "A", WTF::Date.send(:decimal_to_alphabase, 0)
+    assert_equal "B", WTF::Date.send(:decimal_to_alphabase, 1)
+    assert_equal "C", WTF::Date.send(:decimal_to_alphabase, 2)
+    assert_equal "J", WTF::Date.send(:decimal_to_alphabase, 9)
+    assert_equal "Z", WTF::Date.send(:decimal_to_alphabase, 25)
+    assert_equal "BA", WTF::Date.send(:decimal_to_alphabase, 26)
+    assert_equal "BB", WTF::Date.send(:decimal_to_alphabase, 27)
+    assert_equal "BAA", WTF::Date.send(:decimal_to_alphabase, 676)
+    assert_equal "BAB", WTF::Date.send(:decimal_to_alphabase, 677)
+    assert_equal "BAC", WTF::Date.send(:decimal_to_alphabase, 678)
+  end
+
+  def test_alphabase_conversion_with_negative_numbers
+    assert_equal "-B", WTF::Date.send(:decimal_to_alphabase, -1)
+    assert_equal "-C", WTF::Date.send(:decimal_to_alphabase, -2)
+    assert_equal "-BB", WTF::Date.send(:decimal_to_alphabase, -27)
+    assert_equal "-BAA", WTF::Date.send(:decimal_to_alphabase, -676)
+  end
+
+  def test_alphabase_conversion_with_floats
+    assert_raise ArgumentError do
+      WTF::Date.send(:decimal_to_alphabase, 7.7)
+    end
+  end
+
+  def test_time_to_wtf
+    assert_equal "AAAAA", WTF::Date.send(:time_to_wtf, 0) # midnight
+    assert_equal "NAAAA", WTF::Date.send(:time_to_wtf, 12*60*60*1000) # noon
+    assert_equal "BAAAA", WTF::Date.send(:time_to_wtf, 3323077)
+  end
+
+  #---------------------#
+  # Testing public API. #
+  #---------------------#
+
+  def test_converting_to_wtf
+
+    time = Time.utc(1970, 1, 1, 0)
+    wtf = WTF::Date.new(time)
+    assert_equal "FIWIT", wtf.date_part
+    assert_equal "NAAAA", wtf.time_part
+    assert_equal "FIWIT:NAAAA", wtf.as_wtf
+
+    time = Time.utc(1969, 12, 31, 12)
+    wtf = WTF::Date.new(time)
+    assert_equal "FIWIT", wtf.date_part
+    assert_equal "AAAAA", wtf.time_part
+    assert_equal "FIWIT:AAAAA", wtf.as_wtf
+
+    time = Time.utc(2002, 7, 10, 12)
+    wtf = WTF::Date.new(time)
+    assert_equal "FJNXQ", wtf.date_part
+    assert_equal "AAAAA", wtf.time_part
+    assert_equal "FJNXQ:AAAAA", wtf.as_wtf
+
+    time = Time.utc(2002, 7, 10, 13, 55, 1, 777000)
+    wtf = WTF::Date.new(time)
+    assert_equal "FJNXQ", wtf.date_part
+    assert_equal "CCAAA", wtf.time_part
+    assert_equal "FJNXQ:CCAAA", wtf.as_wtf
+
+  end
+
+  def test_converting_to_standard_time
+    time = Time.utc(1970, 1, 1, 0)
+    assert_equal time, WTF::Date.new("FIWIT:NAAAA").as_utc
+    assert_equal time, WTF::Date.new("FIWIT:NAAA").as_utc
+    assert_equal time, WTF::Date.new("FIWIT:NAA").as_utc
+    assert_equal time, WTF::Date.new("FIWIT:NA").as_utc
+    assert_equal time, WTF::Date.new("FIWIT:N").as_utc
+    time = Time.utc(1969, 12, 31, 12)
+    assert_equal time, WTF::Date.new("FIWIT:AAAAA").as_utc
+    assert_equal time, WTF::Date.new("FIWIT:AAAA").as_utc
+    assert_equal time, WTF::Date.new("FIWIT:AAA").as_utc
+    assert_equal time, WTF::Date.new("FIWIT:AA").as_utc
+    assert_equal time, WTF::Date.new("FIWIT:A").as_utc
+    assert_equal time, WTF::Date.new("FIWIT:").as_utc
+    assert_equal time, WTF::Date.new("IWIT:").as_utc
+    assert_equal time, WTF::Date.new("IWIT:A").as_utc
+    assert_equal time, WTF::Date.new("IWIT:AA").as_utc
+    time = Time.utc(2002, 7, 10, 12)
+    assert_equal time, WTF::Date.new("FJNXQ:AAAAA").as_utc
+    assert_equal time, WTF::Date.new("FJNXQ:").as_utc
+    assert_equal time, WTF::Date.new("NXQ:").as_utc
+    time = Time.utc(2002, 7, 10, 13, 55, 1, 777000)
+    assert_in_delta time.to_f, WTF::Date.new("FJNXQ:CCAAA").as_utc.to_f, 0.006
+    assert_in_delta time.to_f, WTF::Date.new("FJNXQ:CC").as_utc.to_f, 0.006
+    assert_equal 12, WTF::Date.new(":AA").as_utc.hour
+    assert_equal 0, WTF::Date.new(":AA").as_utc.min
+    assert_equal 0, WTF::Date.new(":N").as_utc.hour
+    assert_equal 0, WTF::Date.new(":N").as_utc.min
+    assert_equal 0, WTF::Date.new("N").as_utc.hour
+    assert_equal 0, WTF::Date.new("N").as_utc.min
+    assert_equal 12, WTF::Date.new(":").as_utc.hour
+    assert_equal 0, WTF::Date.new(":").as_utc.min
+    assert_raise ArgumentError do
+      WTF::Date.new("").as_utc
+    end
+    assert_raise ArgumentError do
+      WTF::Date.new("ABCDEF:ABC").as_utc # date part can't be longer than five characters
+    end
+    assert_nothing_raised do
+      WTF::Date.new("FJCDE:ABCDEFGHIJ").as_utc # time part can be longer than five characters
+    end
+  end
+
+  def test_now
+    wtf = WTF::Date.now
+    wtf2 = WTF::Date.now
+    time = wtf.as_utc
+    time2 = wtf2.as_utc
+    past = Time.utc(2009, 11, 28)
+    future = Time.utc(2030, 1, 12)
+    assert time <= time2
+    assert time < future
+    assert time > past
+  end
+  
+  def test_convert
+    time = Time.utc(1970, 1, 1, 0)
+    assert_equal time, WTF::Date.convert("FIWIT:NAAAA")
+    assert_equal time, WTF::Date.convert("FIWIT:NAA")
+    assert_equal time, WTF::Date.convert("FIWIT:N")
+    assert_equal time, WTF::Date.convert("IWIT:N")
+    assert_equal "FIWIT:NAAAA", WTF::Date.convert(time)
+  end
+
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: wtf
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Wyatt Greene
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-11-29 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: "\n      The WTF gem provides a Ruby class to convert between standard\n      time and World Time Format.  For more information, visit\n      http://www.worldtimeformat.com\n    "
+email: techiferous@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README
+files: 
+- CHANGELOG
+- LICENSE
+- README
+- Rakefile
+- lib/wtf.rb
+- test/test_helper.rb
+- test/wtf_test.rb
+has_rdoc: true
+homepage: http://github.com/techiferous/wtf
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: 
+- none
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Converts between World Time Format and standard dates and times.
+test_files: 
+- test/test_helper.rb
+- test/wtf_test.rb