time_interval 0.1.0

data/.document

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

data/.gitignore

@@ -0,0 +1,23 @@
+## MAC OS
+.DS_Store
+
+*.gem
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/README.rdoc

@@ -0,0 +1,35 @@
+= time_interval
+
+This is a method for dividing up time into differing units of scale, either
+a constant factor such as binary or a more arbitrary arrangement. This is
+useful for many things, such as indexing a series of linear events and
+being able to group them by different levels of temporal granularity.
+
+Due to the implementation, the limit on dates supported is:
+
+    1970-01-01 00:00:00 UTC - 2038-01-19 03:14:07 UTC
+
+Standard UNIX time is represented by the number of seconds since epoch, that
+being the start of January 1, 1970. Positive values indicate points in time
+after this, and negative values indicate prior to it. This is called a
+time_t type offset, based on the UNIX time_t data type.
+
+TimeInterval is stored as an unsigned 32-bit number by appropriating the
+bit usually reserved for indicating a negative value and using it to encode
+how large or small the interval defined is.
+
+== Example
+
+    # Defaults to the current time
+    interval = TimeInterval.new
+    
+    # Convert to a time grouped by 1<<16 seconds
+    encoded = interval.to_i(16)
+
+    # Decode this time back into a regular time_t offset, but this will
+    # be rounded to 1<<16 second granularity.
+    decoded = TimeInterval.new(encoded)
+
+== Copyright
+
+Copyright (c) 2010 Scott Tadman, The Working Group

data/Rakefile

@@ -0,0 +1,51 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "time_interval"
+    gem.summary = %Q{Calculates time interval subsets}
+    gem.description = %Q{Useful for dividing up linear time into nested intervals}
+    gem.email = "github@tadman.ca"
+    gem.homepage = "http://github.com/tadman/time_interval"
+    gem.authors = %w[ tadman ]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "time_interval #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

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

data/lib/time_interval.rb

@@ -0,0 +1,107 @@
+class TimeInterval
+  # == Constants ============================================================
+  
+  MASK = (0..30).to_a.collect { |i| (1 << 31) - (1 << (30 - i)) }.freeze
+
+  DEFAULT_SCALE = (0..30).to_a.collect { |i| [ i, MASK[i] ] }.freeze
+  DEFAULT_SCALE_NAME = (0..30).to_a.freeze
+  
+  # == Class Methods ========================================================
+  
+  def self.with_definition(definition)
+    scale_defn = nil
+    scale_name_defn = [ ]
+    
+    case (definition)
+    when Array
+      case (definition[0])
+      when String, Symbol
+        definition = [ 1 ] + definition
+      end
+      
+      scale_defn = { }
+      scale_factor = 1
+
+      definition.each_with_index do |element, i|
+        case (i % 2)
+        when 0
+          scale_factor *= element
+        when 1
+          scale_defn[element] = [ MASK[scale_defn.length], scale_factor ]
+          scale_name_defn << element
+        end
+      end
+    else
+      scale = [ ]
+
+      31.times do |i|
+        scale_factor = i ** definition
+        if (scale_factor < (1 << 31))
+          scale_defn.push([ MASK[i], scale_factor ])
+          scale_name_defn << i
+        end
+      end
+    end
+
+    subclass = nil
+    
+    if (scale_defn)
+      subclass = Class.new(self)
+
+      methods = Module.new do
+        define_method(:scale) do
+          scale_defn
+        end
+
+        define_method(:scale_name) do
+          scale_name_defn
+        end
+      end
+      
+      subclass.send(:extend, methods)
+    end
+    
+    subclass or self
+  end
+  
+  def self.interval_to_i(value)
+    value = value.to_i
+
+    if (value < 0)
+      value = -value
+      
+      index = (0..30).to_a.reverse.detect do |i|
+        MASK[i] == value & MASK[i]
+      end
+
+      value = (value ^ MASK[index]) * scale[scale_name[index]][1]
+    end
+    
+    value
+  end
+  
+  def self.scale
+    DEFAULT_SCALE
+  end
+  
+  def self.scale_name
+    DEFAULT_SCALE_NAME
+  end
+  
+  # == Instance Methods =====================================================
+
+  def initialize(value = nil)
+    @time = self.class.interval_to_i(value || Time.now)
+  end
+  
+  def to_i(at_scale = nil)
+    case (at_scale)
+    when nil, 0
+      @time
+    else
+      scale_details = self.class.scale[at_scale]
+      
+      -(scale_details[0] | (@time / scale_details[1]))
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'time_interval'
+
+class Test::Unit::TestCase
+end

data/test/test_time_interval.rb

@@ -0,0 +1,58 @@
+require 'helper'
+
+class TestTimeInterval < Test::Unit::TestCase
+  def test_mask_integrity
+    assert_equal TimeInterval::MASK.length, TimeInterval::MASK.uniq.length
+  end
+
+  def test_default_state
+    interval = TimeInterval.new
+    
+    assert_equal interval.to_i, Time.now.to_i
+  end
+
+  def test_custom_interval
+    # Create a custom interval with a simple definition based on the regular
+    # calendar.
+
+    interval_type = TimeInterval.with_definition(
+      [ :second, 60, :minute, 60, :hour, 24, :day, 7, :week ]
+    )
+    
+    assert_equal 5, interval_type.scale.length
+    
+    # Construct a series of expectations by multiplying out into the
+    # required numbre of seconds.
+    weeks = 5
+    days = 4 + weeks * 7
+    hours = 3 + days * 24
+    minutes = 2 + hours * 60
+    seconds = 1 + minutes * 60
+    
+    # Create an interval with this value
+    interval = interval_type.new(seconds)
+    
+    assert interval
+    
+    # When accessed using the default #to_i conversion method, the value
+    # returned should be seconds since epoch.
+    assert_equal seconds, interval.to_i
+    
+    # Different interval slices can be obtained by passing in the name from
+    # the definition.
+    assert_equal -(TimeInterval::MASK[0] | seconds), interval.to_i(:second)
+    assert_equal -(TimeInterval::MASK[1] | minutes), interval.to_i(:minute)
+    assert_equal -(TimeInterval::MASK[2] | hours), interval.to_i(:hour)
+    assert_equal -(TimeInterval::MASK[3] | days), interval.to_i(:day)
+    assert_equal -(TimeInterval::MASK[4] | weeks), interval.to_i(:week)
+    
+    # These times can be decoded to a value approximately equal to the
+    # original, losing granularity where it has been masked out.
+    
+    assert_equal weeks * 7 * 24 * 60 * 60, interval_type.new(interval.to_i(:week)).to_i
+    assert_equal days * 24 * 60 * 60, interval_type.new(interval.to_i(:day)).to_i
+    assert_equal hours * 60 * 60, interval_type.new(interval.to_i(:hour)).to_i
+    assert_equal minutes * 60, interval_type.new(interval.to_i(:minute)).to_i
+    assert_equal seconds, interval_type.new(interval.to_i(:second)).to_i
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification 
+name: time_interval
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- tadman
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-08-24 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: Useful for dividing up linear time into nested intervals
+email: github@tadman.ca
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/time_interval.rb
+- test/helper.rb
+- test/test_time_interval.rb
+has_rdoc: true
+homepage: http://github.com/tadman/time_interval
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Calculates time interval subsets
+test_files: 
+- test/helper.rb
+- test/test_time_interval.rb