quality_time 0.1.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,10 @@
+
+source "http://rubygems.org"
+
+group :development do
+  gem "rspec"
+  gem "rdoc"
+  gem "bundler"
+  gem "jeweler"
+end
+

data/Gemfile.lock

@@ -0,0 +1,31 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.2.4)
+    git (1.2.5)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.8.0)
+    rake (10.0.4)
+    rdoc (4.0.1)
+      json (~> 1.4)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  jeweler
+  rdoc
+  rspec

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2013 Riley
+
+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.rdoc

@@ -0,0 +1,74 @@
+= QualityTime
+
+QualityTime extends Ruby's standard Time and Date classes to facilitate
+safer and more deliberate manipulation of chronological and calendar
+values, especially for values that precede the introduction of the
+Gregorian calendar.
+
+== Extensions to Date and Time
+
+Date#to_local_time is a Julian-safe replacement for Date#to_time from
+the Ruby standard library. Date#to_utc_time is an equivalent method that
+returns the UTC time corresponding to the beginning of the day denoted
+by Date.
+
+Time#to_gregorian_date and Time#to_julian_date are convenience methods
+which supplement Time#to_date from the Ruby standard library. Unlike
+Time#to_date, these methods return Date objects which use a fixed
+calendar.
+
+== Why Date#to_time is unsafe for Julian values
+
+Dates constructed with a value on or before 1582-10-04 (Julian day 2299160)
+using the default calendar reform day, as well as any Date constructed
+explicitly to use the Julian calendar (Date::JULIAN), are unsafe for use
+with Date#to_time.
+
+Unlike Date objects, which can use either the Julian or Gregorian calendars,
+and are freely convertible between the two, Time objects always use the
+Gregorian calendar, or the "proleptic" Gregorian calendar as it is known
+when it is applied to values before 1582-10-15 (Julian day 2299161).
+
+Ruby standard library Date#to_time does not respect this limitation, with
+the effect that the values of Time objects instantiated from Julian calendar
+Date objects bear only a misleading relationship to the values of the Date
+objects that produce them.
+
+Such an instance of Time will appear to denote the same calendar year,
+month, and day as the Date object it was derived from, but these attributes
+belong to a different calendar than is used by the Date object they were
+derived from.
+
+As one consequence, the Time object cannot be converted back into a
+Date object equivalent to the one it was derived from:
+
+  d = Date.new(1582, 10, 4) # Julian day 229160
+  d == d.to_time.to_date    # false! (Julian day 229150)
+
+Other operations on the Time object derived in this fashion are likely
+to yield misleading results:
+
+  d = Date.new(1582, 10, 4)
+  d.to_time + (60 * 60 * 24)                # Minus 9 days: 2299151j
+  Time.now - d.to_time                      # Includes 10 day error
+  d.to_time.to_date < Date.new(1582, 9, 30) # true
+
+== Why Date#to_local_time and Date#to_utc_time are safe for all values
+
+Date#to_local_time and Date#to_utc_time preserve the relationship between
+the value of the Date object, its chronological Julian day, and the value
+of the Time object, epoch seconds and nanoseconds. By maintaining the
+relationship between these values rather than relying on their
+representations in the Julian or Gregorian calendars, the products of
+these conversions are interoperable:
+
+  d = Date.new(1582, 10, 4)
+  d == d.to_local_time.to_date                    # true
+  Time.now - d.to_local_time                      # Secs since 2299160j
+  d.to_local_time + (60 * 60 * 24)                # Plus 1 day: 2299161j
+  d.to_local_time.to_date < Date.new(1582, 9, 30) # false
+
+== Copyright
+
+Copyright (c) 2013 Riley Lynch. See LICENSE.txt for further details.
+

data/Rakefile

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  gem.name = "quality_time"
+  gem.homepage = "http://github.com/teleological/quality_time"
+  gem.license = "MIT"
+  gem.summary = %Q{Patches Ruby's Time and Date classes to do the right thing}
+  gem.description = <<-TXT
+QualityTime extends Ruby's standard Time and Date classes to facilitate safer and more deliberate manipulation of chronological and calendar values, especially for values that precede the introduction of the Gregorian calendar.
+  TXT
+  gem.email = "oss+time@teleological.net"
+  gem.authors = ["Riley Lynch"]
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "quality_time #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

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

data/lib/core_ext/date.rb

@@ -0,0 +1,32 @@
+
+require 'date'
+
+class Date
+
+  # Returns a local Time object denoting the start (in local time) of the
+  # chronological Julian day represented by the Date. Note that Time objects
+  # always use the Gregorian calendar to calculate civil coordinates such as
+  # month, day and year. This method is intended to replace the standard
+  # Date#to_time method, which produces invalid Time objects for Dates which
+  # use the Julian calendar.
+  def to_local_time
+    Time.local(*gregorian_civil_coordinates)
+  end
+
+  # Returns a UTC Time object denoting the start (in UTC) of the
+  # chronological Julian day represented by the Date.  Note that Time objects
+  # always use the Gregorian calendar to calculate civil coordinates such as
+  # month, day and year.
+  def to_utc_time
+    Time.utc(*gregorian_civil_coordinates)
+  end
+
+  private
+
+  def gregorian_civil_coordinates
+    d = gregorian? ? self : gregorian
+    [ d.year, d.month, d.day ]
+  end
+
+end
+

data/lib/core_ext/time.rb

@@ -0,0 +1,29 @@
+
+require 'date'
+# Time#to_date defined in date library extension
+
+class Time
+
+  # Returns a Date object denoting the chronological Julian day corresponding
+  # to the Time value's Gregorian date. Date objects returned by this method
+  # use the Gregorian calendar or proleptic Gregorian calendar for any value.
+  def to_gregorian_date
+    to_date_with_start(Date::GREGORIAN)
+  end
+
+  # Returns a Date object denoting the chronological Julian day corresponding
+  # to the Time value's Gregorian date. Date objects returned by this method
+  # use the Julian calendar for any value.
+  def to_julian_date
+    to_date_with_start(Date::JULIAN)
+  end
+
+  private
+
+  def to_date_with_start(start)
+    d = to_date
+    d.start == start ? d : d.new_start(start)
+  end
+
+end
+

data/lib/quality_time.rb

@@ -0,0 +1,4 @@
+
+require 'core_ext/date'
+require 'core_ext/time'
+

data/quality_time.gemspec

@@ -0,0 +1,62 @@
+# 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 = "quality_time"
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Riley Lynch"]
+  s.date = "2013-05-17"
+  s.description = "QualityTime extends Ruby's standard Time and Date classes to facilitate safer and more deliberate manipulation of chronological and calendar values, especially for values that precede the introduction of the Gregorian calendar.\n"
+  s.email = "oss+time@teleological.net"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    ".rspec",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "lib/core_ext/date.rb",
+    "lib/core_ext/time.rb",
+    "lib/quality_time.rb",
+    "spec/lib/core_ext/date_spec.rb",
+    "spec/lib/core_ext/time_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = "http://github.com/teleological/quality_time"
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = "1.8.23"
+  s.summary = "Patches Ruby's Time and Date classes to do the right thing"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+      s.add_development_dependency(%q<rdoc>, [">= 0"])
+      s.add_development_dependency(%q<bundler>, [">= 0"])
+      s.add_development_dependency(%q<jeweler>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, [">= 0"])
+      s.add_dependency(%q<rdoc>, [">= 0"])
+      s.add_dependency(%q<bundler>, [">= 0"])
+      s.add_dependency(%q<jeweler>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 0"])
+    s.add_dependency(%q<rdoc>, [">= 0"])
+    s.add_dependency(%q<bundler>, [">= 0"])
+    s.add_dependency(%q<jeweler>, [">= 0"])
+  end
+end
+

data/spec/lib/core_ext/date_spec.rb

@@ -0,0 +1,102 @@
+
+require 'spec_helper'
+
+describe Date do
+  context "with QualityTime extensions" do
+
+    shared_examples_for "a symmetrically convertible Time value" do
+
+      it "returns an equivalent Time for Julian value, Julian start" do
+        d = Date.new(1582, 10, 4)
+        d.send(method).to_date.should == d
+      end
+
+      it "returns an equivalent Time for Julian value, Gregorian start" do
+        d = Date.new(1582, 10, 4, Date::GREGORIAN)
+        d.send(method).to_date.should == d
+      end
+
+      it "returns an equivalent Time for proleptic Gregorian gap value" do
+        d = Date.new(1582, 10, 14, Date::GREGORIAN)
+        d.send(method).to_date.should == d
+      end
+
+      it "returns an equivalent Time for Gregorian value" do
+        d = Date.new(1582, 10, 15)
+        d.send(method).to_date.should == d
+      end
+
+      it "returns an equivalent Time for Gregorian value, Julian start" do
+        d = Date.new(1582, 10, 15, Date::JULIAN)
+        d.send(method).to_date.should == d
+      end
+
+    end
+
+    describe "#to_local_time" do
+
+      let(:method) { :to_local_time }
+
+      it_should_behave_like "a symmetrically convertible Time value"
+
+      it "returns a local Time object" do
+        Date.new.send(method).should_not be_utc
+      end
+
+    end
+
+    describe "#to_utc_time" do
+
+      let(:method) { :to_utc_time }
+
+      it_should_behave_like "a symmetrically convertible Time value"
+
+      it "returns a utc Time object" do
+        Date.new.send(method).should be_utc
+      end
+
+    end
+
+    # The following examples do not specify the behavior of QualityTime
+    # but demonstrate why it's needed: Standard library Date#to_time
+    # doesn't play well with Julian dates
+    describe "#to_time" do
+
+      let(:method) { :to_time }
+
+      it "returns an equivalent Time for Julian value, Julian start" do
+        pending "Date#to_time does not return a valid Time for Julian dates"
+        d = Date.new(1582, 10, 4)
+        d.send(method).to_date.should == d
+      end
+
+      it "returns an equivalent Time for Julian value, Gregorian start" do
+        d = Date.new(1582, 10, 4, Date::GREGORIAN)
+        d.send(method).to_date.should == d
+      end
+
+      it "returns an equivalent Time for proleptic Gregorian gap value" do
+        d = Date.new(1582, 10, 14, Date::GREGORIAN)
+        d.send(method).to_date.should == d
+      end
+
+      it "returns an equivalent Time for Gregorian value" do
+        d = Date.new(1582, 10, 15)
+        d.send(method).to_date.should == d
+      end
+
+      it "returns an equivalent Time for Gregorian value, Julian start" do
+        pending "Date#to_time does not return a valid Time for Julian dates"
+        d = Date.new(1582, 10, 15, Date::JULIAN)
+        d.send(method).to_date.should == d
+      end
+
+      it "returns a local Time object" do
+        Date.new.to_time.should_not be_utc
+      end
+
+    end
+
+  end
+end
+

data/spec/lib/core_ext/time_spec.rb

@@ -0,0 +1,126 @@
+
+require 'spec_helper'
+
+describe Time do
+  context "with QualityTime extensions" do
+
+    shared_examples_for "a symmetrically convertible Date value" do
+
+      it "returns an equivalent Date for value in Julian range" do
+        t = Time.send(constructor, 1582, 10, 4)
+        t.send(method).send(reconverter).should == t
+      end
+
+      it "returns an equivalent Date for value in proleptic Gregorian range" do
+        t = Time.send(constructor, 1582, 10, 14)
+        t.send(method).send(reconverter).should == t
+      end
+
+      it "returns an equivalent Date for value in Gregorian range" do
+        t = Time.send(constructor, 1582, 10, 15)
+        t.send(method).send(reconverter).should == t
+      end
+
+    end
+
+    shared_examples_for "a value convertible to a fixed calendar Date" do
+
+      it "returns an equivalent Date for value in Julian range" do
+        t = Time.send(constructor, 1582, 10, 4)
+        t.send(method).start.should == start_day
+      end
+
+      it "returns an equivalent Date for value in proleptic Gregorian range" do
+        t = Time.send(constructor, 1582, 10, 14)
+        t.send(method).start.should == start_day
+      end
+
+      it "returns an equivalent Date for value in Gregorian range" do
+        t = Time.send(constructor, 1582, 10, 15)
+        t.send(method).start.should == start_day
+      end
+
+    end
+
+    describe "#to_gregorian_date" do
+
+      let(:method)    { :to_gregorian_date }
+      let(:start_day) { Date::GREGORIAN    }
+
+      context "with UTC Time object" do
+
+        let(:constructor) { :utc         }
+        let(:reconverter) { :to_utc_time }
+
+        it_should_behave_like "a symmetrically convertible Date value"
+        it_should_behave_like "a value convertible to a fixed calendar Date"
+
+      end
+
+      context "with local Date object" do
+
+        let(:constructor) { :local         }
+        let(:reconverter) { :to_local_time }
+
+        it_should_behave_like "a symmetrically convertible Date value"
+        it_should_behave_like "a value convertible to a fixed calendar Date"
+
+      end
+
+    end
+
+    describe "#to_julian_date" do
+
+      let(:method)    { :to_julian_date }
+      let(:start_day) { Date::JULIAN    }
+
+      context "with UTC Time object" do
+
+        let(:constructor) { :utc         }
+        let(:reconverter) { :to_utc_time }
+
+        it_should_behave_like "a symmetrically convertible Date value"
+        it_should_behave_like "a value convertible to a fixed calendar Date"
+
+      end
+
+      context "with local Time object" do
+
+        let(:constructor) { :local         }
+        let(:reconverter) { :to_local_time }
+
+        it_should_behave_like "a symmetrically convertible Date value"
+        it_should_behave_like "a value convertible to a fixed calendar Date"
+
+      end
+
+    end
+
+    describe "#to_date" do
+
+      let(:method) { :to_date }
+
+      context "with UTC Time object" do
+
+        let(:constructor) { :utc         }
+        let(:reconverter) { :to_utc_time }
+
+        it_should_behave_like "a symmetrically convertible Date value"
+        # NOTE: start day of Date is variable
+
+      end
+
+      context "with local Time object" do
+
+        let(:constructor) { :local         }
+        let(:reconverter) { :to_local_time }
+
+        it_should_behave_like "a symmetrically convertible Date value"
+
+      end
+
+    end
+
+  end
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'quality_time'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  
+end

metadata

@@ -0,0 +1,133 @@
+--- !ruby/object:Gem::Specification
+name: quality_time
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Riley Lynch
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-05-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ! 'QualityTime extends Ruby''s standard Time and Date classes to facilitate
+  safer and more deliberate manipulation of chronological and calendar values, especially
+  for values that precede the introduction of the Gregorian calendar.
+
+'
+email: oss+time@teleological.net
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.rdoc
+files:
+- .document
+- .rspec
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/core_ext/date.rb
+- lib/core_ext/time.rb
+- lib/quality_time.rb
+- quality_time.gemspec
+- spec/lib/core_ext/date_spec.rb
+- spec/lib/core_ext/time_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/teleological/quality_time
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3390765301944666235
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Patches Ruby's Time and Date classes to do the right thing
+test_files: []