easy_time 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4495654dbc3739198ac730b17b43fd61d66edf258f3a1506e7608414b6e16328
-  data.tar.gz: f3cb77f9f6a71a2d0c48811f3f69153f93678eda2e7510db58fc26657cfe4764
+  metadata.gz: 778f54e349e3d08aa3382639092e1c82bac41c6f2251628daa15e0d916e6bfce
+  data.tar.gz: 07f883f381d1fc7820567efeff2b686343c34b9932d3a9e8427508e1b4dc09b5
 SHA512:
-  metadata.gz: 1bff901b47f340553598a7e1f618faaf011ead4e86c3a32abf84a9edd64afecd043a932811d83a63d6820e319a89fb4c0df2f451733f1c22a5b1465585f83415
-  data.tar.gz: c87ede1b52cd24227c3734c41230af038ee3710ee46dffd9c11776dab8dfe73f8553999e5d04da9ba15f45a4f52a0ebc9133c2a8da228e9c5c2af48240b0bdcc
+  metadata.gz: e89457620f63806559c3c55ea84167eb1ebe1d8649be37cb429b8f4de90585a402b5921cc68cf6e9392fa99ad3a18d218ed2da1c954caeafcb63e0aed762f0d7
+  data.tar.gz: 8f8a023f14f337fe43c3651b684477789f6ce16dd9616d4f8f05e8a9eac82b534dbbed56acd746350da57b932f2fedb7344ba2041f4d573211c37528fc70c7c0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    easy_time (0.1.2)
+    easy_time (0.2.0)
       activesupport
 
 GEM

data/README.md

@@ -137,7 +137,7 @@ A `String` value is parsed with the `convert` method.
 
 Most modern time format strings are recognized: ISO8601, RFD2822, HTTPDate,
 XMLSchema, and even some natural date and time formats.  Many systems use an
-[ISO8601](https://en.wikipedia.org/wiki/ISO_8601) string, which has date, time, 
+[ISO8601](https://en.wikipedia.org/wiki/ISO_8601) string, which has date, time,
 and timezone components, with each variant having some variations.
 
 With `EasyTime`, you don't have to know which time string format to use,
@@ -178,6 +178,18 @@ or
 
     EasyTime.between?(t1, time_range)   # => true if t1 is within the time_range
 
+### Easy Time Arithmetic
+
+These class methods make it easy to do arithmetic on time values and strings.
+
+    EasyTime.add(time1, duration)     # => new EasyTime value
+
+    EasyTime.subtract(time1, time2)   # => duration
+
+    EasyTime.subtract(time, duration) # => new EasyTime value
+
+In the above examples, `time1` can be any of the usual Date and Time classes,
+including a time string value.
 
 ### Configuring the Comparison Tolerance
 
@@ -230,12 +242,12 @@ Arithmetic operators with auto-conversion are also supported:
     t1 - t2
     t1 - duration
 
-The `t2` can be a date, time or even a time string.  In which case, the are
+The `t2` value can be a date, time or even a time string.  In which case, it is
 converted to a `Time` value, and the subtraction is performed between two
-dates, with a duration result.  
+times, with a duration result.
 
 When arithmetic is performed with a `duration` value, then the result is a new
-updated `EasyTime` value
+updated `EasyTime` value.
 
 ### Auto-Conversion Of Comparison Values
 
@@ -280,14 +292,36 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 `rake spec` to run the tests. You can also run `bin/console` for an interactive
 prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To
-release a new version, update the version number in `version.rb`, and then run
-`bundle exec rake release`, which will create a git tag for the version, push
-git commits and tags, and push the `.gem` file to
-[rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. 
+
+## Testing
+
+There is a complete set of tests in the `spec` directory.  To run all the tests:
+
+    bundle exec rake spec
+
+To run all the tests, with `simplecov` code coverage analysis:
+
+    bundle exec rake spec:coverage
+
+Then, to review the code coverage:
+
+    open coverage/index.html
+
+## Additional Documentation
+
+The `easy_time` gem has been developed using `yard` markdown, so it is fairly
+simple to review the gem API documentation:
+
+    bundle exec yard
+    open doc/index.html
 
 ## Contributing
 
+If you wish to contribute, please fork the repo, create a new branch for your suggested
+improvement, and create a pull request based off of your forked repo branch.  Please do
+not make changes in the version.
+
 Bug reports and pull requests are welcome on GitHub at https://github.com/aks/easy_time.
 
 

data/lib/easy_time.rb

@@ -23,25 +23,36 @@ require 'easy_time/convert'
 # `RFC2822`, `HTTPDate`, `XMLSchema`, and `ISO8601` strings and provides
 # comparisons that have an adjustable tolerance.  With `EasyTime` methods, you
 # can reliably compare two timestamps and determine which one is "newer", "older"
-# or the "same" withing a configurable tolerance.  The default comparison
-# tolerance is 1.minute.
+# or the "same" withing a configurable tolerance.
 #
-# In other words, if you have a time-stamp from an `ActiveRecord` object that is
-# a few seconds different from a related object obtained from a 3rd-party system,
-# (eg: AWS S3), then logically, from an application perspective, these two
-# objects could be considered having the "same" time-stamp.
+# The default comparison tolerance is 1 second.  This means that if a local
+# object is created at time t1 and then transferred across the network and used
+# to create a corresponding object in a 3rd-party system, eg: AWS S3, at time
+# t2, then if `(t1 - t2).abs` is < 1.second the two times would be logicall the
+# same.
+#
+# In other words, if you have a time-stamp from an `ActiveRecord` object that
+# is a few milliseconds different from a related object obtained from a
+# 3rd-party system, (eg: AWS S3), then logically, from an application
+# perspective, these two objects could be considered having the "same"
+# time-stamp.
 #
 # This is quite useful when one is trying to keep state synchronized between
 # different systems.  How does one know if an object is "newer" or "older" than
-# that from another system?  If the system time from the connected systems varies
-# by a few or more seconds, then comparisons needs to have some tolerance.
+# that from another system?  If the system time from the connected systems
+# varies by a few or more seconds, then comparisons needs to have some
+# tolerance.
 #
 # Having a tolerant comparison makes "newness" and "oldness" checks easier to
 # manage across systems with possibly varying time sources.
 #
+# However, it is also important to keep the tolerance as small as possible in
+# order to avoid causing more problems, such as false equivalences when objects
+# really were created at different moments in time.
+#
 # `EasyTime` objects are just like Time objects, except:
 #
-# - they auto-convert most date and time objects to Time objects
+# - they auto-convert most time objects, including strings, to Time objects
 # - they provide configurable tolerant comparisons between two time objects
 #
 # Even if you decide to set the configurable comparison tolerance to zero
@@ -56,7 +67,7 @@ require 'easy_time/convert'
 #
 # The conversion to an `EasyTime` can also be provided with a tolerance value:
 #
-#     time.easy_time(tolerance: 5.seconds)
+#     time.easy_time(tolerance: 2.seconds)
 #
 # These are the currently known date and time classes the values of which will
 # be automatically converted to an `EasyTime` value with tolerant comparisons:
@@ -85,7 +96,7 @@ class EasyTime
   #
   #   EasyTime.comparison_tolerance = 0
 
-  DEFAULT_TIME_COMPARISON_TOLERANCE = 1.minute
+  DEFAULT_TIME_COMPARISON_TOLERANCE = 1.second
 
   class << self
     # @example These comparison methods observe the comparison tolerance
@@ -160,6 +171,27 @@ class EasyTime
       new(time1, tolerance: tolerance) <=> time2
     end
 
+    # These methods make it easy to add or subtract dates and durations
+    #     EasyTime.add(time, duration, tolerance: nil)
+    #     EasyTime.subtract(time, time_or_duration, tolerance: nil)
+
+    # @param time [Time,DateTime,ActiveSupport::TimeWithZone,Date,String,Integer,Array<Integer>] a time value
+    # @param duration [ActiveSupport::Duration,Integer,Float] a duration value
+    # @return [EasyTime] the `time` with the `duration` added
+
+    def add(time, duration)
+      EasyTime.new(time) + duration
+    end
+
+    # @param time [Time,DateTime,ActiveSupport::TimeWithZone,Date,String,Integer,Array<Integer>] a time value
+    # @param time_or_duration [Time,DateTime,ActiveSupport::Duration,Integer,Float] a time or duration value
+    # @return [EasyTime,Duration] an `EasyTime` value, when a duration is subtracted from a time, or
+    #         a duration _(Integer)_ value, when one time is subtracted from another time.
+
+    def subtract(time, time_or_duration)
+      EasyTime.new(time) - time_or_duration
+    end
+
     attr_writer :comparison_tolerance
 
     # Class methods to set the class-level comparison tolerance
@@ -287,7 +319,7 @@ class EasyTime
 
   def <=>(other)
     diff = self - other  # note: this has a side-effect of setting @other_time
-    if diff && diff.abs.to_i <= comparison_tolerance.to_i
+    if diff && diff.to_i.abs <= comparison_tolerance.to_i
       0
     elsif diff
       time <=> other_time

data/lib/easy_time/version.rb

@@ -1,3 +1,3 @@
 class EasyTime
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: easy_time
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Alan Stebbens