time_date_helpers 0.0.1 → 0.0.2

data/README.mkd

@@ -0,0 +1,59 @@
+time_date_helpers
+==========
+This is a series of methods written to handle time and date issues in Ruby and/or Rails.  To be honest, it is more of a teaching example than anything else at this point as there are Ruby equivalents (like strftime) that users may prefer.  The original application was handling time and date issues of a ice cream shop application (tracking shift start and end times, dates for assignments and the like).  In the class we created some modules in lib/ to add custom methods and in the next step we moved those methods into a gem (i.e., time_date_helpers).
+
+Installation
+------------
+Installing this gem is pretty simple -- just type on the command line:
+
+```  
+$ gem install time_date_helpers 
+```
+
+And add this gem into any other code with:
+
+```  
+require 'rubygems'
+require 'chronic' 
+require 'time_date_helpers' 
+```
+Note that in irb the chronic gem is required for some of the date helpers. There is a dependency specified in the gem for chronic.
+
+
+Usage
+------------
+There are basically two sections to this gem:
+
+* Date helpers
+* Time helpers
+
+(Note: SpaceTime helpers will be added _relatively_ soon...)
+
+
+### Date helpers ###
+
+Most are self-explanatory and some may have other Ruby equivalents already. 
+Right now all I have in here are three formatting/conversion methods, but might expand this over time to add some other useful methods.  The methods in this module were included in Object, so you can access them directly within main, if you wish.
+
+**humanize_date** -- This simply takes a date or datetime and converts it to the standard mm/dd/yyyy display using strftime.  If you pass in the optional argument :style => :full, then you will get the output formatted as full month name, day and year (e.g., "January 15, 1929"). (This latter option also controls for the weird issue with strftime adding a space to the day if it is less than 10; see tests for examples.)
+
+**convert_to_date** -- This takes a string and attempts to parse it using the Chronic gem.  If the date_string can be parsed, then it will return a date; else it will return nil. Because it uses chronic, it can take strings like "tomorrow" or "yesterday at 3pm" or "1 hour ago" and process them into datetime stamps. In this case, however, we are returning a date object, not a datetime object.
+
+**convert_to_datetime** -- Just like the previous method, this takes a string and attempts to parse it using the Chronic gem.  If the date_string can be parsed, then it will return a datetime; else it will return nil.  The returning value is a datetime object.
+
+
+### Time helpers ###
+
+Most are self-explanatory and some may have other Ruby equivalents already. 
+(Actually, there is only two methods right now...)  The methods in this module were included in Object, so you can access them directly within main, if you wish.
+
+**round_minutes** -- Round the minutes in an hour up or down given a particular interval. The default setting is to round up based on the quarter-hour (15 minute intervals).  For example, by default using this method would result in _9:04 # => 9:15; 9:42 # => 9:45; 9:55 # => 10:00_.  You can pass along two options: direction (:up or :down) and increment (1 to 59).  For example, round_minutes(time1, :increment => 10, :direction => :down) would round the minutes of time1 down to the closest 10 minute interval (e.g., 9:42 # => 9:40).
+
+Since as noted earlier this was used to manage start and end times of shifts, the method will stop any rounding up at the top of the hour.  Hence, if you had 8 minute increments and the minutes passed in was 59, it would round up to 00 and the next hour, not to 04 and the next hour.
+
+**humanize_time** -- Similar to humanize_date, except that the default display is a 12-hour clock with am/pm and no seconds.  If the option :ampm => false is included, then military (24-hour clock) is used.  If the option :with_seconds => true is included, then seconds will be added to the display.
+
+
+### Note on usage ###
+
+This gem has a set of basic unit tests associated with it.  The tests provide other examples of what is possible using this methods and may help the user further understand how this gem can be applied.

data/lib/time_date_helpers/time_helpers.rb

@@ -34,6 +34,21 @@ module TimeDateHelpers
       # Finally, return the adjusted time
       Time.new(time.year, time.month, time.day, (time.hour+hr_adj), new_min, 0)
     end
+    
+    def humanize_time(time, opt={})
+      # Set the default options
+      options = {:ampm => true, :with_seconds => false}
+      # Merge whatever options the user has selected with the defaults
+      options.merge!(opt)
+      # Make sure what is passed is legit
+      return nil if time.nil? 
+      return nil unless time.class == Time
+      if options[:ampm]
+        options[:with_seconds] ? time.strftime("%I:%M:%S %P") : time.strftime("%I:%M %P")
+      else
+        options[:with_seconds] ? time.strftime("%H:%M:%S") : time.strftime("%H:%M")
+      end
+    end
   end
 end
 

data/lib/time_date_helpers/version.rb

@@ -1,3 +1,3 @@
 module TimeDateHelpers
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/tests/date_tests.rb

@@ -0,0 +1,75 @@
+require 'test/unit'
+require 'chronic'
+require 'time_date_helpers'
+
+class DateHelperTests < Test::Unit::TestCase
+  
+  # Test humanize_date method
+  def test_humanize_date_works
+    date1 = Time.new(1776, 07, 04, 0, 0, 0)
+    date2 = Date.new(1929, 01, 15)
+    date3 = DateTime.new(1986, 10, 04, 0, 0, 0)
+    date4 = Time.new(2012, 12, 25, 0, 0, 0)
+    assert_equal '07/04/1776', humanize_date(date1)
+    assert_equal '01/15/1929', humanize_date(date2)
+    assert_equal '10/04/1986', humanize_date(date3)
+    assert_equal '12/25/2012', humanize_date(date4)
+  end
+  
+  def test_humanize_date_works_with_option
+    date1 = Time.new(1776, 07, 04, 0, 0, 0)
+    date2 = Date.new(1929, 01, 15)
+    date3 = DateTime.new(1986, 10, 04, 0, 0, 0)
+    date4 = Time.new(2012, 12, 25, 0, 0, 0)
+    assert_equal 'July 4, 1776', humanize_date(date1, :style => :full)
+    assert_equal 'January 15, 1929', humanize_date(date2, :style => :full)
+    assert_equal 'October 4, 1986', humanize_date(date3, :style => :full)
+    assert_equal 'December 25, 2012', humanize_date(date4, :style => :full)
+  end
+  
+  def test_humanize_date_fails_for_nondates
+    date1 = nil
+    date2 = "10/04/1986"
+    date3 = 3.14159
+    assert_nil humanize_date(date1)
+    assert_nil humanize_date(date2)
+    assert_nil humanize_date(date3)
+  end
+  
+  # Test convert_to_date
+  def test_convert_to_date_works
+    date1 = "10/04/1986"
+    date2 = "tomorrow"
+    date3 = "yesterday at 3pm"
+    date4 = "2012-12-25"
+    date5 = "April 1, 1999"
+    assert_equal 10, convert_to_date(date1).month
+    assert_equal Date.today + 1, convert_to_date(date2)
+    assert_equal Date.today - 1, convert_to_date(date3)
+    assert_equal 25, convert_to_date(date4).day
+    assert_equal 1999, convert_to_date(date5).year
+    assert_nil convert_to_date(nil)
+    assert_nil convert_to_date("FRED!")
+    assert_nil convert_to_date(3.14159)
+  end
+  
+  # Test test_convert_to_datetime
+  def test_convert_to_datetime_works
+    datetime1 = "10/04/1986"
+    datetime2 = "tomorrow"
+    datetime3 = "yesterday at 3pm"
+    datetime4 = "2012-12-25 08:46:01"
+    datetime5 = "April 1, 1999 at 10pm"
+    datetime6 = "1 hour ago"
+    today = Date.today
+    assert_equal 10, convert_to_datetime(datetime1).month
+    assert_equal Time.new((today).year, (today).month, (today+1).day, 12, 0, 0), convert_to_datetime(datetime2)
+    assert_equal Time.new((today).year, (today).month, (today-1).day, 15, 0, 0), convert_to_datetime(datetime3)
+    assert_equal 8, convert_to_datetime(datetime4).hour
+    assert_equal 22, convert_to_datetime(datetime5).hour
+    assert_equal (Time.now - 3600).hour, convert_to_datetime(datetime6).hour
+    assert_nil convert_to_datetime(nil)
+    assert_nil convert_to_datetime("FRED!")
+    assert_nil convert_to_datetime(3.14159)
+  end 
+end

data/tests/time_tests.rb

@@ -0,0 +1,120 @@
+require 'test/unit'
+require 'time_date_helpers'
+
+class TimeHelperTests < Test::Unit::TestCase
+  
+  def test_default_settings
+    quarter1 = Time.new(2012, 04, 30, 9, 6, 0)
+    quarter2 = Time.new(2012, 04, 30, 9, 16, 0)
+    quarter3 = Time.new(2012, 04, 30, 9, 36, 0)
+    quarter4 = Time.new(2012, 04, 30, 9, 46, 0)
+    assert_equal('09:15', round_minutes(quarter1).strftime('%H:%M'))
+    assert_equal('09:30', round_minutes(quarter2).strftime('%H:%M'))
+    assert_equal('09:45', round_minutes(quarter3).strftime('%H:%M'))
+    assert_equal('10:00', round_minutes(quarter4).strftime('%H:%M'))
+  end
+  
+  def test_even_increments
+    # Test cases where total segments is an integer (i.e., 60%increment==0)
+    inc = 10
+    time1 = Time.new(2012, 04, 30, 9, 6, 0)
+    time2 = Time.new(2012, 04, 30, 9, 16, 0)
+    time3 = Time.new(2012, 04, 30, 9, 36, 0)
+    time4 = Time.new(2012, 04, 30, 9, 46, 0)
+    time5 = Time.new(2012, 04, 30, 9, 50, 0)
+    time6 = Time.new(2012, 04, 30, 9, 56, 0)
+    assert_equal('09:10', round_minutes(time1, :increment => inc).strftime('%H:%M'))
+    assert_equal('09:20', round_minutes(time2, :increment => inc).strftime('%H:%M'))
+    assert_equal('09:40', round_minutes(time3, :increment => inc).strftime('%H:%M'))
+    assert_equal('09:50', round_minutes(time4, :increment => inc).strftime('%H:%M'))
+    assert_equal('09:50', round_minutes(time5, :increment => inc).strftime('%H:%M'))
+    assert_equal('10:00', round_minutes(time6, :increment => inc).strftime('%H:%M'))
+  end
+  
+  def test_uneven_increments
+    # Test cases where total segments is not an integer (i.e., 60%increment!=0)
+    inc = 8
+    time1 = Time.new(2012, 04, 30, 9, 6, 0)
+    time2 = Time.new(2012, 04, 30, 9, 16, 0)
+    time3 = Time.new(2012, 04, 30, 9, 34, 0)
+    time4 = Time.new(2012, 04, 30, 9, 46, 0)
+    time5 = Time.new(2012, 04, 30, 9, 56, 0)
+    time6 = Time.new(2012, 04, 30, 9, 59, 0)
+    assert_equal('09:08', round_minutes(time1, :increment => inc).strftime('%H:%M'))
+    assert_equal('09:16', round_minutes(time2, :increment => inc).strftime('%H:%M'))
+    assert_equal('09:40', round_minutes(time3, :increment => inc).strftime('%H:%M'))
+    assert_equal('09:48', round_minutes(time4, :increment => inc).strftime('%H:%M'))
+    assert_equal('09:56', round_minutes(time5, :increment => inc).strftime('%H:%M'))
+    assert_equal('10:00', round_minutes(time6, :increment => inc).strftime('%H:%M'))
+  end
+  
+  def test_direction_down
+    quarter1 = Time.new(2012, 04, 30, 9, 6, 0)
+    quarter2 = Time.new(2012, 04, 30, 9, 16, 0)
+    quarter3 = Time.new(2012, 04, 30, 9, 36, 0)
+    quarter4 = Time.new(2012, 04, 30, 9, 46, 0)
+    assert_equal('09:00', round_minutes(quarter1, :direction => :down).strftime('%H:%M'))
+    assert_equal('09:15', round_minutes(quarter2, :direction => :down).strftime('%H:%M'))
+    assert_equal('09:30', round_minutes(quarter3, :direction => :down).strftime('%H:%M'))
+    assert_equal('09:45', round_minutes(quarter4, :direction => :down).strftime('%H:%M'))
+  end
+  
+  def test_increments_and_direction_together
+    inc = 8
+    time1 = Time.new(2012, 04, 30, 9, 6, 0)
+    time2 = Time.new(2012, 04, 30, 9, 16, 0)
+    time3 = Time.new(2012, 04, 30, 9, 34, 0)
+    time4 = Time.new(2012, 04, 30, 9, 46, 0)
+    time5 = Time.new(2012, 04, 30, 9, 56, 0)
+    time6 = Time.new(2012, 04, 30, 9, 59, 0)
+    assert_equal('09:00', round_minutes(time1, :increment => inc, :direction => :down).strftime('%H:%M'))
+    assert_equal('09:16', round_minutes(time2, :increment => inc, :direction => :down).strftime('%H:%M'))
+    assert_equal('09:32', round_minutes(time3, :increment => inc, :direction => :down).strftime('%H:%M'))
+    assert_equal('09:40', round_minutes(time4, :direction => :down, :increment => inc).strftime('%H:%M'))
+    assert_equal('09:56', round_minutes(time5, :direction => :down, :increment => inc).strftime('%H:%M'))
+    assert_equal('09:56', round_minutes(time6, :direction => :down, :increment => inc).strftime('%H:%M'))
+  end
+  
+  # Test humanize_time
+  def test_humanize_time_works
+    time1 = Time.new(2012, 01, 01, 0, 0, 0)
+    time2 = Time.new(2012, 01, 01, 9, 36, 59)
+    time3 = Time.new(2012, 01, 01, 11, 11, 11)
+    time4 = Time.new(2012, 01, 01, 15, 14, 15)
+    assert_equal '12:00 am', humanize_time(time1)
+    assert_equal '09:36 am', humanize_time(time2)
+    assert_equal '11:11 am', humanize_time(time3)
+    assert_equal '03:14 pm', humanize_time(time4)
+  end
+  
+  def test_humanize_time_works_with_military_time
+    time1 = Time.new(2012, 01, 01, 0, 0, 0)
+    time2 = Time.new(2012, 01, 01, 9, 36, 59)
+    time3 = Time.new(2012, 01, 01, 11, 11, 11)
+    time4 = Time.new(2012, 01, 01, 15, 14, 15)
+    assert_equal '00:00', humanize_time(time1, :ampm => false)
+    assert_equal '09:36', humanize_time(time2, :ampm => false)
+    assert_equal '11:11', humanize_time(time3, :ampm => false)
+    assert_equal '15:14', humanize_time(time4, :ampm => false)
+  end
+  
+  def test_humanize_time_works_with_seconds_option
+    time1 = Time.new(2012, 01, 01, 0, 0, 0)
+    time2 = Time.new(2012, 01, 01, 9, 36, 59)
+    time3 = Time.new(2012, 01, 01, 11, 11, 11)
+    time4 = Time.new(2012, 01, 01, 15, 14, 15)
+    assert_equal '12:00:00 am', humanize_time(time1, :with_seconds => true)
+    assert_equal '09:36:59 am', humanize_time(time2, :with_seconds => true)
+    assert_equal '11:11:11 am', humanize_time(time3, :with_seconds => true)
+    assert_equal '03:14:15 pm', humanize_time(time4, :with_seconds => true)
+  end
+  
+  def test_humanize_time_fails_for_nondates
+    time1 = nil
+    time2 = "10/04/1986"
+    time3 = 3.14159
+    assert_nil humanize_time(time1)
+    assert_nil humanize_time(time2)
+    assert_nil humanize_time(time3)
+  end
+end

data/time_date_helpers.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |s|
   s.version     = TimeDateHelpers::VERSION
   s.authors     = ["Klingon Code Warrior"]
   s.email       = ["profh@cmu.edu"]
-  s.homepage    = ""
+  s.homepage    = "https://github.com/profh/time_date_helpers"
   s.summary     = %q{A series of helpers to deal with time and date issues in Rails.}
   s.description = %q{The initial version has only a few date and time helpers and was created primarily for teaching purposes (how to create gems), but does have some value. I will try to get back to this gem and add more methods as time allows.}
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: time_date_helpers
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chronic
-  requirement: &2153346800 !ruby/object:Gem::Requirement
+  requirement: &2154777240 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2153346800
+  version_requirements: *2154777240
 - !ruby/object:Gem::Dependency
   name: chronic
-  requirement: &2153362400 !ruby/object:Gem::Requirement
+  requirement: &2154776540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2153362400
+  version_requirements: *2154776540
 description: The initial version has only a few date and time helpers and was created
   primarily for teaching purposes (how to create gems), but does have some value.
   I will try to get back to this gem and add more methods as time allows.
@@ -44,13 +44,16 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - Gemfile
+- README.mkd
 - Rakefile
 - lib/time_date_helpers.rb
 - lib/time_date_helpers/date_helpers.rb
 - lib/time_date_helpers/time_helpers.rb
 - lib/time_date_helpers/version.rb
+- tests/date_tests.rb
+- tests/time_tests.rb
 - time_date_helpers.gemspec
-homepage: ''
+homepage: https://github.com/profh/time_date_helpers
 licenses: []
 post_install_message: 
 rdoc_options: []