unix_epoch 0.1.0

data/README.rdoc

@@ -0,0 +1,54 @@
+= unix_epoch
+
+* http://github.com/chetan/unix_epoch
+
+== DESCRIPTION:
+
+Ruby library that adds the following methods to the DateTime class for handling
+Unix timestamps.
+
+  * from_unix_ts(unix_ts, offset)
+  * to_unix_ts()
+  * to_i()
+
+One advantage of using this library over Time.at() is the correct handling of
+very large dates (> 2038) on 32-bit systems.
+
+== DOCUMENTATION:
+
+Documentation is available online at at rdoc.info[http://rdoc.info/projects/chetan/unix_epoch]
+
+== SYNOPSIS:
+
+  require "unix_epoch"
+  dt = DateTime.from_unix_ts(1301103992)
+  dt.to_i == 1301103992
+
+== INSTALL:
+
+  sudo gem install unix_epoch
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2011 Pixelcop Research, Inc.
+
+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/Rakefile

@@ -0,0 +1,30 @@
+
+begin
+  require 'rubygems'
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "unix_epoch"
+    gemspec.summary = "Adds methods to DateTime for dealing with Unix Timestamps"
+    gemspec.description = "Adds from_unix_ts and to_unix_ts methods to the DateTime class"
+    gemspec.email = "chetan@pixelcop.net"
+    gemspec.homepage = "http://github.com/chetan/unix_epoch"
+    gemspec.authors = ["Chetan Sarva"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler"
+end
+
+require "rake/testtask"
+desc "Run unit tests"
+Rake::TestTask.new("test") { |t|
+    #t.libs << "test"
+    t.ruby_opts << "-rubygems"
+    t.pattern = "test/**/*_test.rb"
+    t.verbose = false
+    t.warning = false
+}
+
+require "yard"
+YARD::Rake::YardocTask.new("docs") do |t|
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/unix_epoch.rb

@@ -0,0 +1,125 @@
+
+# concept borrowed from Perl's DateTime::Format::Epoch on CPAN
+# instead of Rata Die (RD), we use Julian Date (JD), which is
+# better understood by Ruby's DateTime library
+
+require 'date'
+
+module UnixEpoch
+
+    module ClassMethods
+
+        # Create a new DateTime object from a given Unix Timestamp
+        #
+        # @param [Fixnum, Bignum] unix_ts       seconds since unix epoch (1970-01-01 00:00:00 UTC)
+        # @param [Fixnum] offset        offset in seconds from UTC time
+        # @return [DateTime]            DateTime object representation of the given Unix TS
+        def from_unix_ts(unix_ts, offset = 0)
+
+            # step 1) get the delta in days, seconds and nano seconds represented by unix_ts
+
+            delta_days = UnixEpoch._floor(unix_ts / 86_400)
+            unix_ts -= delta_days * 86_400
+
+            # unix_ts cannot be negative now, so to_i instead of _floor()
+            delta_secs = unix_ts.to_i
+            unix_ts -= delta_secs
+
+            delta_nano = unix_ts / 1e9
+
+            # step 2) add these deltas to the jd day and jd sec representation of the unix epoch
+
+            epoch_jd = UnixEpoch.jd_unix_epoch()
+
+            epoch_jd_days = epoch_jd.to_i
+            epoch_secs = UnixEpoch.get_jd_secs(epoch_jd) # get left over seconds from our epoch
+
+            jd_days = epoch_jd_days + delta_days
+
+            secs = epoch_secs + delta_secs + offset # add tz offset back in also
+            jd_secs = UnixEpoch.secs_to_jd_secs(secs) + Rational(delta_nano.round, 86_400_000_000)
+
+            return DateTime.from_jd(jd_days, jd_secs, offset)
+        end
+
+    end
+
+    module InstanceMethods
+
+        # Converts the current Date & Time into a Fixnum or Bignum representing
+        # the Unix Timestamp
+        #
+        # @return [Fixnum, Bignum]      unix timestamp
+        def to_unix_ts
+            delta_days = self.jd - UnixEpoch.jd_unix_epoch()
+            unix_ts = delta_days * 86_400
+            h, m, s = self.class.day_fraction_to_time(day_fraction)
+            delta_secs = h * 3600 + m * 60 + s
+            delta_secs -= UnixEpoch.jd_fr_to_secs(offset) if offset != 0 # remove tz offset to get back to UTC
+            unix_ts += delta_secs
+        end
+
+        # (see #to_unix_ts)
+        def to_i
+            self.to_unix_ts
+        end
+
+    end
+
+
+    private
+
+    # Returns a Julian Date representing the Unix Epoch (January 1, 1970 00:00:00 UTC)
+    #
+     # @return [Fixnum]  Julian Date representing the Unix Epoch
+    def self.jd_unix_epoch
+        Date.civil(1970, 1, 1).jd
+    end
+
+    # Convert the given number of seconds into a JD fraction
+    #
+    # @return [Rational]    JD fraction representing the time
+    def self.secs_to_jd_secs(secs)
+      Rational(secs, 86_400)
+    end
+
+    # Retrieve the seconds part of the given Julian Date
+	#
+	# @param [Float]	Julian Date including fractional value (e.g., 2455647.543)
+	# @return [Fixnum]	Number of seconds represented by the fractional value
+    def self.get_jd_secs(jd)
+        jd_fr_to_secs(jd % 1)
+    end
+
+    # Convert the given Julian Date fractional value into seconds
+	#
+	# @param [Float]	Julian Date fractional value (e.g., 0.543)
+	# @return [Fixnum]	Number of seconds represented by the fractional value
+    def self.jd_fr_to_secs(fr)
+        h, m, s = DateTime.day_fraction_to_time(fr)
+        (h * 3600 + m * 60 + s)
+    end
+
+    def self._floor(x)
+        ix = x.to_i
+        if ix <= x then
+            return ix
+        end
+        return ix - 1
+    end
+
+end
+
+class DateTime
+
+    extend UnixEpoch::ClassMethods
+    include UnixEpoch::InstanceMethods
+
+    # Create a new DateTime object from a given JD
+    #
+    # +sg+ specifies the Day of Calendar Reform.
+    def self.from_jd(jd, fr, of = 0, sg=ITALY)
+        of = Rational(of, 86_400) if of != 0 and not of.kind_of? Rational
+        new!(jd_to_ajd(jd, fr, of), of, sg)
+    end
+end

data/test/unix_epoch_test.rb

@@ -0,0 +1,44 @@
+
+require 'test/unit'
+require 'unix_epoch'
+
+class UnixEpoch_Test < Test::Unit::TestCase
+
+    def setup
+        @f = "%Y-%m-%d %H:%M:%S"
+    end
+
+    def test_from_unix_ts
+        i = 1301103992
+        assert DateTime.from_unix_ts(i).strftime(@f) == Time.at(i).utc.strftime(@f)
+    end
+
+    def test_from_unix_ts_large_date
+        # date > 2038
+        i = 2240611200
+        assert DateTime.from_unix_ts(i).strftime(@f) == Time.at(i).utc.strftime(@f)
+    end
+
+    def test_from_unix_ts_localtime
+        i = 1301103992
+        assert DateTime.from_unix_ts(i, Time.new.utc_offset).strftime(@f) == Time.at(i).strftime(@f)
+    end
+
+    def test_to_unix_ts
+        i = 1301103992
+        d = DateTime.from_unix_ts(i)
+        t = Time.at(i)
+        assert d.strftime(@f) == t.utc.strftime(@f)
+        assert t.to_i == i
+        assert d.to_unix_ts == i
+    end
+
+    def test_to_unix_ts_localtime
+        i = 1301103992
+        d = DateTime.from_unix_ts(i, Time.new.utc_offset)
+        t = Time.at(i)
+        assert d.strftime(@f) == t.strftime(@f)
+        assert t.to_i == i
+        assert d.to_unix_ts == i
+    end
+end

data/unix_epoch.gemspec

@@ -0,0 +1,43 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{unix_epoch}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Chetan Sarva"]
+  s.date = %q{2011-03-26}
+  s.description = %q{Adds from_unix_ts and to_unix_ts methods to the DateTime class}
+  s.email = %q{chetan@pixelcop.net}
+  s.extra_rdoc_files = [
+    "README.rdoc"
+  ]
+  s.files = [
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "lib/unix_epoch.rb",
+    "test/unix_epoch_test.rb",
+    "unix_epoch.gemspec"
+  ]
+  s.homepage = %q{http://github.com/chetan/unix_epoch}
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.5.0}
+  s.summary = %q{Adds methods to DateTime for dealing with Unix Timestamps}
+  s.test_files = [
+    "test/unix_epoch_test.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: unix_epoch
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Chetan Sarva
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-26 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: Adds from_unix_ts and to_unix_ts methods to the DateTime class
+email: chetan@pixelcop.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/unix_epoch.rb
+- test/unix_epoch_test.rb
+- unix_epoch.gemspec
+has_rdoc: true
+homepage: http://github.com/chetan/unix_epoch
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.5.0
+signing_key: 
+specification_version: 3
+summary: Adds methods to DateTime for dealing with Unix Timestamps
+test_files: 
+- test/unix_epoch_test.rb