units-time 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3894ab823f4d595259a95b23637fa877737a7632
-  data.tar.gz: d9a684989b45c322a6ad86af619ca107a9d588eb
+  metadata.gz: cd753e92ae05a7b8124067b1530096616392cb33
+  data.tar.gz: 16ded8e6519cdc289e8ea6f452a7e985571ac602
 SHA512:
-  metadata.gz: a08e3e095f76c77428ffdeb0ae5816b092a43a531266156750cbb2eccc7fb5ed969c35b83656d2c3b78ec1f5b44cc52255f7b167222097583465398a97313c7c
-  data.tar.gz: 86c076784ddd8dead6797d797fce9adccb75bcce43cf04e22df5b676a9d3dd67ab1c355605ff79196c0c8758935f67f0f5923b96f9ffe5ea3045013cea27c49e
+  metadata.gz: d2e4132b9194102097f6ebcfbf1c78145f6467965c19df49d30b61808b5732a168c38e00af35a371af8357d34bc730568be7bf628c87f075d276851098d4ea65
+  data.tar.gz: 0c3f079769f959f77f58913f79396a87bbbed7032b5fe435933f7ac6e3c3fc715fd91352412d3afca32362d56025f745d72052f7b0cdb75ffd8120650bce5113

data/README.md

@@ -11,7 +11,93 @@ units-time library / gem - units of time (in epoch time) incl. seconds, minutes,
 
 ## Usage
 
-to be done
+[Timestamp](#timestamp) • [Timedelta](#timedelta)
+
+
+The following methods are added on `Integer` (`Fixnum` and `Bignum`)
+and always return a `Timedelta` object (in seconds):
+
+``` ruby
+# plural versions
+2.seconds       #=> <Timedelta seconds=2>
+2.secs          #=> <Timedelta seconds=2>
+3.minutes       #=> <Timedelta seconds=180>
+3.mins          #=> <Timedelta seconds=180>
+4.hours         #=> <Timedelta seconds=14_400>
+5.days          #=> <Timedelta seconds=432_000>
+6.weeks         #=> <Timedelta seconds=3_628_800>
+7.fortnights    #=> <Timedelta seconds=8_467_200>
+8.years         #=> <Timedelta seconds=252_288_000>
+
+# singular versions
+1.second        #=> <Timedelta seconds=1>
+1.sec           #=> <Timedelta seconds=1>
+1.minute        #=> <Timedelta seconds=60>
+1.min           #=> <Timedelta seconds=60>
+1.hour          #=> <Timedelta seconds=3600>
+1.day           #=> <Timedelta seconds=86_400>
+1.week          #=> <Timedelta seconds=604_800>
+1.fortnight     #=> <Timedelta seconds=1_209_600>
+1.year          #=> <Timedelta seconds=31_536_000>
+```
+
+
+### Time arithmetics
+
+You can add and subtract durations from `Timestamp` or `Timedelta` objects.
+
+``` ruby
+Timestamp.now + 2.hours      #=> <Timestamp seconds= >
+1.week + 1.day               #=> <Timedelta seconds= >
+2.minutes - 1.second         #=> <TimeDelta seconds= >
+```
+
+Note: You CANNOT add or subtract integers to `Timestamp` or `Timedelta` objects
+and vice versa.
+
+``` ruby
+# Bad
+10 + 1.minute   #=> Boom! <TypeError>
+1.minute + 10   #=> Boom! <TypeError>
+
+# Good
+10.seconds + 1.minute   #=> <Timedelta seconds=70>
+1.minute.to_i + 10      #=> Integer
+```
+
+Note: Multiply an integer with `1.hour` or `1.minute` or `1.second` and so on
+to convert to a time unit.
+
+``` ruby
+100*1.hour              #=> <Timedelta seconds=360_000>
+```
+
+
+### Timestamp
+
+The `Timestamp` class holds the time in seconds since unix epoch time (that is, January 1st, 1970).
+
+``` ruby
+Timestamp.new(0)   # or Timestamp(0)
+```
+
+To get the time now use:
+
+``` ruby
+Timestamp.now      # or Timestamp.new
+```
+
+
+
+### Timedelta
+
+The `Timedelta` class holds a time duration in seconds.
+
+``` ruby
+Timedelta.new     # or Timedelta(0)
+```
+
+
 
 
 ## License

data/lib/units-time.rb

@@ -1,12 +1,8 @@
 # encoding: utf-8
 
-##
-#  todo/fix: use module
-##   use Timestamp and Timedelta classes etc.
-
-
 ## stdlibs
 require 'pp'
+require 'time'
 
 
 ## our own code
@@ -14,52 +10,226 @@ require 'units-time/version'    # note: let version always go first
 
 
 
+#########################
+# type constraints:
+#
+#   note: for now
+#    - you CANNOT add a timestamp to another timestamp
+#    - you CAN only compare (<=>) timestamp to timestamp but NOT timedelta !!
+#    - you CAN only compare (<=>) timedelta to timedelta but NOT timestamp !!
+
+class Timestamp
+
+  def self.now() new( Time.now.to_i ); end
+
+  attr_reader :seconds
+
+  def initialize( seconds=Time.now.to_i )
+    @seconds = seconds    ## seconds since Jan 1st, 1970 (unix epoch time)
+  end
+
+  def ==( other )
+    if other.is_a?( self.class )
+      @seconds == other.seconds
+    else
+      ## note: allow for now integer comparision too - why? why not?
+      if other.is_a?( Integer )
+        @seconds == other
+      else
+        false
+      end
+    end
+  end
+  alias_method :eql?, :==
+
+  def +( other )
+    if other.is_a?( Timedelta )
+      self.class.new( @seconds + other.seconds )
+    else
+      ## fix/todo: use TypeError!!!!
+      raise ArgumentError.new( "[Timestamp] add(ition) - wrong type #{other.inspect} - Timedelta expected" )
+    end
+  end
+
+  def -( other )
+    if other.is_a?( Timedelta )
+      self.class.new( @seconds - other.seconds )
+    else
+      ## fix/todo: use TypeError!!!!
+      raise ArgumentError.new( "[Timestamp] sub(straction) - wrong type #{other.inspect} - Timedelta expected" )
+    end
+  end
+
+
+  include Comparable
+
+  def <=>( other )
+    if other.is_a?( self.class )
+      @seconds <=> other.seconds
+    else
+      ## fix/todo: use TypeError!!!!
+      raise ArgumentError.new( "[Timestamp] <=> - wrong type #{other.inspect} - Timestamp expected" )
+    end
+  end
+
+
+  ## todo/fix: always freeze by default (timestamp is immutable) - why? why not?
+  def self.zero()  @@zero ||= new(0).freeze; end
+
+  alias_method :to_i,   :seconds     ## add to integer conversion - why? why not?
+  alias_method :to_int, :seconds
+end  ## class Timestamp
+
+
+
+class Timedelta
+
+  attr_reader :seconds
+
+  def initialize( seconds=0 )
+    @seconds = seconds
+  end
+
+
+  def ==( other )
+    if other.is_a?( self.class )
+      @seconds == other.seconds
+    else
+      ## note: allow for now integer comparision too - why? why not?
+      if other.is_a?( Integer )
+        @seconds == other
+      else
+        false
+      end
+    end
+  end
+  alias_method :eql?, :==
+
+  def *( other )
+    if other.is_a?( Integer )
+      self.class.new( @seconds * other )
+    else
+      ## fix/todo: use TypeError!!!!
+      raise ArgumentError.new( "[Timedelta] mul(tiplication) - wrong type #{other.inspect} - integer number expected" )
+    end
+  end
+
+  def +( other )
+    if other.is_a?( self.class )
+      self.class.new( @seconds + other.seconds )
+    else
+      ## fix/todo: use TypeError!!!!
+      raise ArgumentError.new( "[Timedelta] add(ition) - wrong type #{other.inspect} - Timedelta expected" )
+    end
+  end
+
+  def -( other )
+    if other.is_a?( self.class )
+      self.class.new( @seconds - other.seconds )
+    else
+      ## fix/todo: use TypeError!!!!
+      raise ArgumentError.new( "[Timedelta] sub(straction) - wrong type #{other.inspect} - Timedelta expected" )
+    end
+  end
+
+
+  ### for details on coerce
+  ##   see https://blog.dnsimple.com/2017/01/ruby-coercion-protocols-part-2/
+  def coerce( other )
+    if other.is_a?( Integer )
+      [self, other]    ## allow communitative - switch left and right e.g. 365*24.hours to 24.hours*365
+    else
+      ## fix/todo: use TypeError!!!!
+      raise ArgumentError.new( "[Timedelta] coerce - wrong type #{other.inspect} - Integer number expected" )
+    end
+  end
+
+
+  include Comparable
+
+  def <=>( other )
+    if other.is_a?( self.class )
+      @seconds <=> other.seconds
+    else
+      ## fix/todo: use TypeError!!!!
+      raise ArgumentError.new( "[Timedelta] <=> - wrong type #{other.inspect} - Timedelta expected" )
+    end
+  end
+
+
+  ## todo/fix: always freeze by default (timedelta is immutable) - why? why not?
+  def self.zero()  @@zero ||= new(0).freeze; end
 
-class Integer
-
+  alias_method :to_i,   :seconds     ## add to integer conversion - why? why not?
+  alias_method :to_int, :seconds
+  ## note: same as:
+  ##  def to_i()   @seconds; end    ## add to integer conversion - why? why not?
+  ##  def to_int() @seconds; end
+end # class Timedelta
+
+
+### "global" converter functions use like
+##    Timestamp(0)  or Timedelta(0)
+def Timestamp(arg) Timestamp.new( arg ); end
+def Timedelta(arg) Timedelta.new( arg ); end
+
+
+
+module TimeUnits
   ######################################
   ## note: there's NO month (for now)!!!
   ##   why?  month might be 28,29,30,31  days
   ##    use days e.g. 30.days or 31.days etc.
 
+
   HOUR_IN_SECONDS       =  60 * 60                # 60 minutes * 60 seconds
   DAY_IN_SECONDS        =  24 * HOUR_IN_SECONDS   # 24 hours * 60 * 60
   WEEK_IN_SECONDS       =   7 * DAY_IN_SECONDS    #  7 days * 24 * 60 * 60
   FORTNIGHT_IN_SECONDS  =  14 * DAY_IN_SECONDS    # 14 days * 24 * 60 * 60
+
+  #####
+  #  note: for year use 365 days for now and NOT 365.25 (1/4)
+  #    - why? why not? discuss
   YEAR_IN_SECONDS       = 365 * DAY_IN_SECONDS    # 365 days * 24 * 60 * 60
 
-  def second()    self; end
-  def minute()    self * 60; end
-  def hour()      self * HOUR_IN_SECONDS; end
-  def day()       self * DAY_IN_SECONDS;  end
-  def week()      self * WEEK_IN_SECONDS; end
-  def fortnight() self * FORTNIGHT_IN_SECONDS; end
-  def year()      self * YEAR_IN_SECONDS; end
+  def second()    Timedelta.new( self ); end
+  def minute()    Timedelta.new( self * 60 ); end
+  def hour()      Timedelta.new( self * HOUR_IN_SECONDS ); end
+  def day()       Timedelta.new( self * DAY_IN_SECONDS );  end
+  def week()      Timedelta.new( self * WEEK_IN_SECONDS ); end
+  def fortnight() Timedelta.new( self * FORTNIGHT_IN_SECONDS ); end
+  def year()      Timedelta.new( self * YEAR_IN_SECONDS ); end
+
 
   ########################################################
-  ## alias - use alias or alias_method - why? why not?
-  def seconds() second; end
-  def secs()    second; end
-  def sec()     second; end
-  def s()       second; end
+  ## alias
+  alias_method :seconds, :second
+  alias_method :secs,    :second
+  alias_method :sec,     :second
+  ## def s()       second; end     ### todo/fix: remove/add - why? why not?
+
+  alias_method :minutes, :minute
+  alias_method :mins,    :minute
+  alias_method :min,     :minute
+  ## def m()       minute; end    ### todo/fix: remove/add - why? why not?
 
-  def minutes() minute; end
-  def mins()    minute; end
-  def min()     minute; end
-  def m()       minute; end
+  alias_method :hours,   :hour
+  ## def h()       hour; end      ### todo/fix: remove/add - why? why not?
 
-  def hours()   hour; end
-  def h()       hour; end
+  alias_method :days,    :day
+  ## def d()    day; end          ### todo/fix: remove/add - why? why not?
 
-  def days() day; end
-  def d()    day; end
+  alias_method :weeks,   :week
+  ## def w()     week; end        ### todo/fix: remove/add - why? why not?
 
-  def weeks() week; end
-  def w()     week; end
+  alias_method :fortnights, :fortnight
 
-  def fortnights() fortnight; end
+  alias_method :years, :year
+  ## def y()     year; end        ### todo/fix: remove/add - why? why not?
+end  # module TimeUnits
 
-  def years() year; end
-  def y()     year; end
 
+
+class Integer
+   include TimeUnits
 end # class Integer

data/lib/units-time/version.rb

@@ -2,9 +2,9 @@
 
 module UnitsTime
 
-  MAJOR = 0
+  MAJOR = 1
   MINOR = 0
-  PATCH = 1
+  PATCH = 0
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 
   def self.version

data/test/test_units_time.rb

@@ -10,66 +10,103 @@ require 'helper'
 
 class TestUnitsTime < MiniTest::Test
 
-def test_time
-  now = Time.now.to_i
-
-  assert_equal 31_536_000,      1.year
-  assert_equal 31_536_000,      1.y
-  assert_equal 31_536_000*2,    2.years
-  assert_equal 31_536_000*2,    1.y*2
-  assert_equal now+31_536_000,  now+1.year
-  assert_equal 31_536_000,      365.days
-  assert_equal 31_536_000,      365*24.hours
-
-  assert_equal 1_209_600,     1.fortnight
-  assert_equal 1_209_600*2,   2.fortnights
-  assert_equal 1_209_600*2,   1.fortnight*2
-  assert_equal now+1_209_600, now+1.fortnight
-  assert_equal 1_209_600,     2.weeks
-  assert_equal 1_209_600,     14.days
-  assert_equal 1_209_600,     14*24.hours
-
-  assert_equal 604_800,       1.week
-  assert_equal 604_800,       1.w
-  assert_equal 604_800*2,     2.weeks
-  assert_equal 604_800*2,     1.week*2
-  assert_equal now+604_800,   now+1.week
-  assert_equal 604_800,       7.days
-  assert_equal 604_800,       7*24.hours
-
-  assert_equal 86_400,     1.day
-  assert_equal 86_400,     1.d
-  assert_equal 86_400*2,   2.days
-  assert_equal 86_400*2,   1.day*2
-  assert_equal now+86_400, now+1.day
-  assert_equal 86_400,     24.hours
-  assert_equal 86_400,     24*1.hour
-
-  assert_equal 3600,     1.hour
-  assert_equal 3600,     1.h
-  assert_equal 3600*2,   2.hours
-  assert_equal 3600*2,   1.hour*2
-  assert_equal now+3600, now+1.hour
-  assert_equal 3600,     60.minutes
-  assert_equal 3600,     60*1.minute
-
-  assert_equal 60,       1.minute
-  assert_equal 60,       1.min
-  assert_equal 60,       1.m
-  assert_equal 60*2,     2.minutes
-  assert_equal 60*2,     2.mins
-  assert_equal 60*2,     1.minute*2
-  assert_equal now+60,   now+1.minute
-  assert_equal 60,       60.seconds
-  assert_equal 60,       60*1.second
-
-  assert_equal 1,     1.second
-  assert_equal 1,     1.sec
-  assert_equal 1,     1.s
-  assert_equal 1*2,   2.seconds
-  assert_equal 1*2,   2.secs
-  assert_equal 1*2,   1.second*2
-  assert_equal now+1, now+1.second
+def test_timstamp
+  now = Timestamp.now
+
+  assert_equal now.to_i, now
+
+  assert_equal now+31_536_000.secs,  now+1.year
+  assert_equal now+1_209_600.secs,   now+1.fortnight
+  assert_equal now+604_800.secs,     now+1.week
+  assert_equal now+86_400.secs,      now+1.day
+  assert_equal now+3600.secs,        now+1.hour
+  assert_equal now+60.secs,          now+1.minute
+  assert_equal now+1.sec,            now+1.second
+
+  assert_equal true,  now+1.second >  now
+  assert_equal true,  now+1.second >= now
+  assert_equal false, now+1.second <  now
+  assert_equal false, now+1.second <= now
+end
+
+
+def test_timedelta
+  assert_equal 31_536_000.secs,      1.year
+  ## assert_equal 31_536_000,      1.y
+  assert_equal 31_536_000.secs*2,    2.years
+  assert_equal 31_536_000.secs*2,    1.year*2
+  ## assert_equal 31_536_000*2,    1.y*2
+  assert_equal 31_536_000.secs,      365.days
+  assert_equal 31_536_000.secs,      24.hours*365  ## note: uses coerce for type coercion
+  assert_equal 31_536_000.secs,      365*24.hours
+
+  assert_equal 1_209_600.secs,     1.fortnight
+  assert_equal 1_209_600.secs*2,   2.fortnights
+  assert_equal 1_209_600.secs*2,   1.fortnight*2
+  assert_equal 1_209_600.secs,     2.weeks
+  assert_equal 1_209_600.secs,     14.days
+  assert_equal 1_209_600.secs,     14*24.hours  ## note: uses coerce for type coercion
+  assert_equal 1_209_600.secs,     24.hours*14
+
+  assert_equal 604_800.secs,       1.week
+  ## assert_equal 604_800,       1.w
+  assert_equal 604_800.secs*2,     2.weeks
+  assert_equal 604_800.secs*2,     1.week*2
+  assert_equal 604_800.secs,       7.days
+  assert_equal 604_800.secs,       7*24.hours  ## note: uses coerce for type coercion
+  assert_equal 604_800.secs,       24.hours*7
+
+  assert_equal 86_400.secs,     1.day
+  ## assert_equal 86_400,     1.d
+  assert_equal 86_400.secs*2,   2.days
+  assert_equal 86_400.secs*2,   1.day*2
+  assert_equal 86_400.secs,     24.hours
+  assert_equal 86_400.secs,     24*1.hour  ## note: uses coerce for type coercion
+  assert_equal 86_400.secs,     1.hour*24
+
+  assert_equal 3600.secs,     1.hour
+  ## assert_equal 3600,     1.h
+  assert_equal 3600.secs*2,   2.hours
+  assert_equal 3600.secs*2,   1.hour*2
+  assert_equal 3600.secs,     60.minutes
+  assert_equal 3600.secs,     60*1.minute  ## note: uses coerce for type coercion
+  assert_equal 3600.secs,     1.minute*60
+
+  assert_equal 60.secs,       1.minute
+  assert_equal 60.secs,       1.min
+  ## assert_equal 60,       1.m
+  assert_equal 60.secs*2,     2.minutes
+  assert_equal 60.secs*2,     2.mins
+  assert_equal 60.secs*2,     1.minute*2
+  assert_equal 60.secs,       60.seconds
+  assert_equal 60.secs,       60*1.second  ## note: uses coerce for type coercion
+  assert_equal 60.secs,       1.second*60
+
+  assert_equal 1.sec,     1.second
+  assert_equal 1.sec,     1.sec
+  ## assert_equal 1,     1.s
+  assert_equal 1.sec*2,   2.seconds
+  assert_equal 1.sec*2,   2.secs
+  assert_equal 1.sec*2,   1.second*2
+end
+
+def test_timedelta_ops
+  assert_equal (31_536_000+1_209_600+604_800).secs, 1.year+1.fortnight+1.week
+
+  now = Timestamp.now
+  assert_equal Timedelta,         (100 * 1.hour).class
+  assert_equal now+100*3600.secs, now + (100 * 1.hour)
+  assert_equal Timestamp,         (now + (100 * 1.hour)).class
+end
+
+def test_conv
+  assert_equal Timestamp.new(0), Timestamp(0)
+  assert_equal Timedelta.new,    Timedelta(0)
+
+  assert_equal Timestamp.zero, Timestamp(0)
+  assert_equal Timedelta.zero, Timedelta(0)
+
+  assert_equal 0.secs, Timedelta(0)
 end
 
 end # class TestUnitsTime

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: units-time
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-09 00:00:00.000000000 Z
+date: 2019-03-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc