easy_time 0.1.2 → 0.2.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/Gemfile.lock +1 -1
- data/README.md +43 -9
- data/lib/easy_time.rb +44 -12
- data/lib/easy_time/version.rb +1 -1
- metadata +1 -1
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 778f54e349e3d08aa3382639092e1c82bac41c6f2251628daa15e0d916e6bfce
|
4
|
+
data.tar.gz: 07f883f381d1fc7820567efeff2b686343c34b9932d3a9e8427508e1b4dc09b5
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: e89457620f63806559c3c55ea84167eb1ebe1d8649be37cb429b8f4de90585a402b5921cc68cf6e9392fa99ad3a18d218ed2da1c954caeafcb63e0aed762f0d7
|
7
|
+
data.tar.gz: 8f8a023f14f337fe43c3651b684477789f6ce16dd9616d4f8f05e8a9eac82b534dbbed56acd746350da57b932f2fedb7344ba2041f4d573211c37528fc70c7c0
|
data/Gemfile.lock
CHANGED
data/README.md
CHANGED
@@ -137,7 +137,7 @@ A `String` value is parsed with the `convert` method.
|
|
137
137
|
|
138
138
|
Most modern time format strings are recognized: ISO8601, RFD2822, HTTPDate,
|
139
139
|
XMLSchema, and even some natural date and time formats. Many systems use an
|
140
|
-
[ISO8601](https://en.wikipedia.org/wiki/ISO_8601) string, which has date, time,
|
140
|
+
[ISO8601](https://en.wikipedia.org/wiki/ISO_8601) string, which has date, time,
|
141
141
|
and timezone components, with each variant having some variations.
|
142
142
|
|
143
143
|
With `EasyTime`, you don't have to know which time string format to use,
|
@@ -178,6 +178,18 @@ or
|
|
178
178
|
|
179
179
|
EasyTime.between?(t1, time_range) # => true if t1 is within the time_range
|
180
180
|
|
181
|
+
### Easy Time Arithmetic
|
182
|
+
|
183
|
+
These class methods make it easy to do arithmetic on time values and strings.
|
184
|
+
|
185
|
+
EasyTime.add(time1, duration) # => new EasyTime value
|
186
|
+
|
187
|
+
EasyTime.subtract(time1, time2) # => duration
|
188
|
+
|
189
|
+
EasyTime.subtract(time, duration) # => new EasyTime value
|
190
|
+
|
191
|
+
In the above examples, `time1` can be any of the usual Date and Time classes,
|
192
|
+
including a time string value.
|
181
193
|
|
182
194
|
### Configuring the Comparison Tolerance
|
183
195
|
|
@@ -230,12 +242,12 @@ Arithmetic operators with auto-conversion are also supported:
|
|
230
242
|
t1 - t2
|
231
243
|
t1 - duration
|
232
244
|
|
233
|
-
The `t2` can be a date, time or even a time string. In which case,
|
245
|
+
The `t2` value can be a date, time or even a time string. In which case, it is
|
234
246
|
converted to a `Time` value, and the subtraction is performed between two
|
235
|
-
|
247
|
+
times, with a duration result.
|
236
248
|
|
237
249
|
When arithmetic is performed with a `duration` value, then the result is a new
|
238
|
-
updated `EasyTime` value
|
250
|
+
updated `EasyTime` value.
|
239
251
|
|
240
252
|
### Auto-Conversion Of Comparison Values
|
241
253
|
|
@@ -280,14 +292,36 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
|
|
280
292
|
`rake spec` to run the tests. You can also run `bin/console` for an interactive
|
281
293
|
prompt that will allow you to experiment.
|
282
294
|
|
283
|
-
To install this gem onto your local machine, run `bundle exec rake install`.
|
284
|
-
|
285
|
-
|
286
|
-
|
287
|
-
|
295
|
+
To install this gem onto your local machine, run `bundle exec rake install`.
|
296
|
+
|
297
|
+
## Testing
|
298
|
+
|
299
|
+
There is a complete set of tests in the `spec` directory. To run all the tests:
|
300
|
+
|
301
|
+
bundle exec rake spec
|
302
|
+
|
303
|
+
To run all the tests, with `simplecov` code coverage analysis:
|
304
|
+
|
305
|
+
bundle exec rake spec:coverage
|
306
|
+
|
307
|
+
Then, to review the code coverage:
|
308
|
+
|
309
|
+
open coverage/index.html
|
310
|
+
|
311
|
+
## Additional Documentation
|
312
|
+
|
313
|
+
The `easy_time` gem has been developed using `yard` markdown, so it is fairly
|
314
|
+
simple to review the gem API documentation:
|
315
|
+
|
316
|
+
bundle exec yard
|
317
|
+
open doc/index.html
|
288
318
|
|
289
319
|
## Contributing
|
290
320
|
|
321
|
+
If you wish to contribute, please fork the repo, create a new branch for your suggested
|
322
|
+
improvement, and create a pull request based off of your forked repo branch. Please do
|
323
|
+
not make changes in the version.
|
324
|
+
|
291
325
|
Bug reports and pull requests are welcome on GitHub at https://github.com/aks/easy_time.
|
292
326
|
|
293
327
|
|
data/lib/easy_time.rb
CHANGED
@@ -23,25 +23,36 @@ require 'easy_time/convert'
|
|
23
23
|
# `RFC2822`, `HTTPDate`, `XMLSchema`, and `ISO8601` strings and provides
|
24
24
|
# comparisons that have an adjustable tolerance. With `EasyTime` methods, you
|
25
25
|
# can reliably compare two timestamps and determine which one is "newer", "older"
|
26
|
-
# or the "same" withing a configurable tolerance.
|
27
|
-
# tolerance is 1.minute.
|
26
|
+
# or the "same" withing a configurable tolerance.
|
28
27
|
#
|
29
|
-
#
|
30
|
-
#
|
31
|
-
#
|
32
|
-
#
|
28
|
+
# The default comparison tolerance is 1 second. This means that if a local
|
29
|
+
# object is created at time t1 and then transferred across the network and used
|
30
|
+
# to create a corresponding object in a 3rd-party system, eg: AWS S3, at time
|
31
|
+
# t2, then if `(t1 - t2).abs` is < 1.second the two times would be logicall the
|
32
|
+
# same.
|
33
|
+
#
|
34
|
+
# In other words, if you have a time-stamp from an `ActiveRecord` object that
|
35
|
+
# is a few milliseconds different from a related object obtained from a
|
36
|
+
# 3rd-party system, (eg: AWS S3), then logically, from an application
|
37
|
+
# perspective, these two objects could be considered having the "same"
|
38
|
+
# time-stamp.
|
33
39
|
#
|
34
40
|
# This is quite useful when one is trying to keep state synchronized between
|
35
41
|
# different systems. How does one know if an object is "newer" or "older" than
|
36
|
-
# that from another system? If the system time from the connected systems
|
37
|
-
# by a few or more seconds, then comparisons needs to have some
|
42
|
+
# that from another system? If the system time from the connected systems
|
43
|
+
# varies by a few or more seconds, then comparisons needs to have some
|
44
|
+
# tolerance.
|
38
45
|
#
|
39
46
|
# Having a tolerant comparison makes "newness" and "oldness" checks easier to
|
40
47
|
# manage across systems with possibly varying time sources.
|
41
48
|
#
|
49
|
+
# However, it is also important to keep the tolerance as small as possible in
|
50
|
+
# order to avoid causing more problems, such as false equivalences when objects
|
51
|
+
# really were created at different moments in time.
|
52
|
+
#
|
42
53
|
# `EasyTime` objects are just like Time objects, except:
|
43
54
|
#
|
44
|
-
# - they auto-convert most
|
55
|
+
# - they auto-convert most time objects, including strings, to Time objects
|
45
56
|
# - they provide configurable tolerant comparisons between two time objects
|
46
57
|
#
|
47
58
|
# Even if you decide to set the configurable comparison tolerance to zero
|
@@ -56,7 +67,7 @@ require 'easy_time/convert'
|
|
56
67
|
#
|
57
68
|
# The conversion to an `EasyTime` can also be provided with a tolerance value:
|
58
69
|
#
|
59
|
-
# time.easy_time(tolerance:
|
70
|
+
# time.easy_time(tolerance: 2.seconds)
|
60
71
|
#
|
61
72
|
# These are the currently known date and time classes the values of which will
|
62
73
|
# be automatically converted to an `EasyTime` value with tolerant comparisons:
|
@@ -85,7 +96,7 @@ class EasyTime
|
|
85
96
|
#
|
86
97
|
# EasyTime.comparison_tolerance = 0
|
87
98
|
|
88
|
-
DEFAULT_TIME_COMPARISON_TOLERANCE = 1.
|
99
|
+
DEFAULT_TIME_COMPARISON_TOLERANCE = 1.second
|
89
100
|
|
90
101
|
class << self
|
91
102
|
# @example These comparison methods observe the comparison tolerance
|
@@ -160,6 +171,27 @@ class EasyTime
|
|
160
171
|
new(time1, tolerance: tolerance) <=> time2
|
161
172
|
end
|
162
173
|
|
174
|
+
# These methods make it easy to add or subtract dates and durations
|
175
|
+
# EasyTime.add(time, duration, tolerance: nil)
|
176
|
+
# EasyTime.subtract(time, time_or_duration, tolerance: nil)
|
177
|
+
|
178
|
+
# @param time [Time,DateTime,ActiveSupport::TimeWithZone,Date,String,Integer,Array<Integer>] a time value
|
179
|
+
# @param duration [ActiveSupport::Duration,Integer,Float] a duration value
|
180
|
+
# @return [EasyTime] the `time` with the `duration` added
|
181
|
+
|
182
|
+
def add(time, duration)
|
183
|
+
EasyTime.new(time) + duration
|
184
|
+
end
|
185
|
+
|
186
|
+
# @param time [Time,DateTime,ActiveSupport::TimeWithZone,Date,String,Integer,Array<Integer>] a time value
|
187
|
+
# @param time_or_duration [Time,DateTime,ActiveSupport::Duration,Integer,Float] a time or duration value
|
188
|
+
# @return [EasyTime,Duration] an `EasyTime` value, when a duration is subtracted from a time, or
|
189
|
+
# a duration _(Integer)_ value, when one time is subtracted from another time.
|
190
|
+
|
191
|
+
def subtract(time, time_or_duration)
|
192
|
+
EasyTime.new(time) - time_or_duration
|
193
|
+
end
|
194
|
+
|
163
195
|
attr_writer :comparison_tolerance
|
164
196
|
|
165
197
|
# Class methods to set the class-level comparison tolerance
|
@@ -287,7 +319,7 @@ class EasyTime
|
|
287
319
|
|
288
320
|
def <=>(other)
|
289
321
|
diff = self - other # note: this has a side-effect of setting @other_time
|
290
|
-
if diff && diff.abs
|
322
|
+
if diff && diff.to_i.abs <= comparison_tolerance.to_i
|
291
323
|
0
|
292
324
|
elsif diff
|
293
325
|
time <=> other_time
|
data/lib/easy_time/version.rb
CHANGED