time_math2 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 76771d4aa5435a2100af858a4bd4851ef81d35c9
-  data.tar.gz: 23abf05b1c0b3dd19a6552619cda98e360b73840
+  metadata.gz: 8fe3eec624d634487ddc4b74d08a3d39ec3f34d5
+  data.tar.gz: 87c691b0990e5e4a03f7bad4602e8bf100d1d526
 SHA512:
-  metadata.gz: a314061838072dac1c4bec199a7a1128f74732a3a0cc041996674e1b6d91a35b53cdd7f7800a9b187108afd73d03027e4e6776c9c5b53f3393df06b2f13d0231
-  data.tar.gz: 192e2f2f194d52dc4d39868ccae10d83bab53350b63177725c3677c2e607574463420d62eab0c6151741747a1a0fe44de408cc103713319d3de607907ef8bf9e
+  metadata.gz: 8a7e17f5d2f9768c734649768b95c8ad63f168ca3c8686f2d52440caa952f8c7a20bc1af223cb5238eacfdec7e5924e814c0d8385887e83a5623da0024d15a55
+  data.tar.gz: a39344389ba42191d780257d97e4c53e6e2e84a5512e7deac17ba731a543e5decab9e01e833b266dc6f93efbbdec1d11135deff8cb78110071535ef382c713a7

data/CHANGELOG.md

@@ -1,5 +1,18 @@
-# TimeBoots changelog
+# TimeMath Changelog
 
-# 0.0.2 (2016-05-27)
+# 0.0.5 (2016-06-25)
 
-* Add support for `DateTime`.
+* Add optional second argument to rounding functions (`floor`, `ceil` and
+  so on), for "floor to 3-hour mark";
+* Allow this argument, as well as in `advance`/`decrease`, to be non-integer;
+  so, you can do `hour.advance(tm, 1/2r)` now;
+* Drop any `core_ext`s completely, even despite it was optional;
+* Add `Op` chainable operations concept (and drop `Span`, which
+  is inferior to it);
+* Redesign `Sequence` creation, allow include/exclude end;
+* Add (experimental) resampling feature.
+
+# 0.0.4 (2016-05-28)
+
+* First "real" release with current name, `Time` and `DateTime` support,
+  proper documentation and stuff.

data/README.md

@@ -11,23 +11,45 @@ arithmetics easier. It provides you with simple, easy-to-remember API, without
 any monkey-patching of core Ruby classes, so it can be used alongside
 Rails or without it, for any purpose.
 
+## Table Of Contents
+
+* [Features](#features)
+* [Naming](#naming)
+* [Reasons](#reasons)
+* [Installation](#installation)
+* [Usage](#usage)
+    - [Full list of simple arithmetic methods](#full-list-of-simple-arithmetic-methods)
+    - [Set of operations as a value object](#set-of-operations-as-a-value-object)
+    - [Time sequence abstraction](#time-sequence-abstraction)
+    - [Measuring time periods](#measuring-time-periods)
+    - [Resampling](#resampling)
+* [Notes on timezones](#notes-on-timezones)
+* [Compatibility notes](#compatibility-notes)
+* [Alternatives](#alternatives)
+* [Links](#links)
+* [Author](#author)
+* [License](#license)
+
 ## Features
 
-* No monkey-patching of core classes (opt-in patching of Time and DateTime
-  provided, though);
-* Works with Time and DateTime;
+* No monkey-patching of core classes (now **strict**; previously existing opt-in
+  core ext removed in 0.0.5);
+* Works with Time, Date and DateTime;
 * Accurately preserves timezone info;
 * Simple arithmetics: floor/ceil/round to any time unit (second, hour, year
   or whatnot), advance/decrease by any unit;
-* Simple time span abstraction (like "5 years" object you can store and
-  pass to other methods);
-* Easy generation of time sequences (like "each day from _this_ to _that_
-  date");
-* Measuring of time distances between two timestamps in any units.
+* Chainable [operations](#set-of-operations-as-a-value-object), including
+  construction of "set of operations" value object (like "10:20 at next
+  month first day"), clean and powerful;
+* Easy generation of [time sequences](#time-sequence-abstraction)
+  (like "each day from _this_ to _that_ date");
+* Measuring of time distances between two timestamps in any units;
+* Powerful and flexible [resampling](#resampling) of arbitrary time value
+  arrays/hashes into regular sequences.
 
 ## Naming
 
-`TimeMath` is the better name I know for the task library does, but
+`TimeMath` is the best name I know for the task library does, yet
 it is [already taken](https://rubygems.org/gems/time_math). So, with no
 other thoughts I came with the ugly solution.
 
@@ -96,21 +118,55 @@ TimeMath.day.advance(Time.now, +10) # => 2016-06-07 14:06:57 +0300
 * `<unit>.range(tm, amount)` -- creates range of `tm ... tm + amount <units>`;
 * `<unit>.range_back(tm, amount)` -- creates range of `tm - amount <units> ... tm`.
 
+**Things to note**:
+
+* rounding methods (`floor`, `ceil` and company) support optional second
+  argument—amount of units to round to, like "each 3 hours": `hour.floor(tm, 3)`;
+* both rounding and advance/decrease methods allow their last argument to
+  be float/rational, so you can `hour.advance(tm, 1/2r)` and this would
+  work as you may expect. Non-integer arguments are only supported for
+  units less than week (because "half of month" have no exact mathematical
+  sense).
+
 See also [Units::Base](http://www.rubydoc.info/gems/time_math2/TimeMath/Units/Base).
 
-### Time span abstraction
+### Set of operations as a value object
 
-`TimeMath::Span` is a simple abstraction of "N units of time", which you
-can store in variable and then apply to some time value:
+For example, you want "10 am at next monday". By using atomic time unit
+operations, you'll need the code like:
 
 ```ruby
-span = TimeMath.day.span(5)
-# => #<TimeMath::Span(day): +5>
-span.before(Time.now)
-# => 2016-05-23 17:46:13 +0300
+TimeMath.hour.advance(TimeMath.week.ceil(Time.now), 10)
 ```
+...which is not really readable, to say the least. So, `TimeMath` provides
+one top-level method allowing to chain any operations you want:
+
+```ruby
+TimeMath(Time.now).ceil(:week).advance(:hour, 10).call
+```
+
+Much more readable, huh?
 
-See also [Span YARD docs](http://www.rubydoc.info/gems/time_math2/TimeMath/Span).
+The best thing about it, that you can prepare "operations list" value
+object, and then use it (or pass to methods, or
+serialize to YAML and deserialize in some Sidekiq task and so on):
+
+```ruby
+op = TimeMath().ceil(:week).advance(:hour, 10)
+# => #<TimeMath::Op ceil(:week).advance(:hour, 10)>
+op.call(Time.now)
+# => 2016-06-27 10:00:00 +0300
+
+# It also can be called on several arguments/array of arguments:
+op.call(tm1, tm2, tm3)
+op.call(array_of_timestamps)
+# ...or even used as a block-ish object:
+array_of_timestamps.map(&op)
+```
+
+See also [TimeMath()](http://www.rubydoc.info/gems/time_math2/toplevel#TimeMath-instance_method)
+and underlying [TimeMath::Op](http://www.rubydoc.info/gems/time_math2/TimeMath/Op)
+class docs.
 
 ### Time sequence abstraction
 
@@ -122,8 +178,8 @@ to = Time.now
 # => 2016-05-28 17:47:30 +0300
 from = TimeMath.day.floor(to)
 # => 2016-05-28 00:00:00 +0300
-seq = TimeMath.hour.sequence(from, to)
-# => #<TimeMath::Sequence(2016-05-28 00:00:00 +0300 - 2016-05-28 17:47:30 +0300)>
+seq = TimeMath.hour.sequence(from...to)
+# => #<TimeMath::Sequence(:hour, 2016-05-28 00:00:00 +0300...2016-05-28 17:47:30 +0300)>
 p(*seq)
 # 2016-05-28 00:00:00 +0300
 # 2016-05-28 01:00:00 +0300
@@ -136,11 +192,21 @@ p(*seq)
 # ...and so on
 ```
 
+Note that sequence also play well with operation chain described above,
+so you can
+
+```ruby
+seq = TimeMath.day.sequence(Time.parse('2016-05-01')...Time.parse('2016-05-04')).advance(:hour, 10).decrease(:min, 5)
+# => #<TimeMath::Sequence(:day, 2016-05-01 00:00:00 +0300...2016-05-04 00:00:00 +0300).advance(:hour, 10).decrease(:min, 5)>
+seq.to_a
+# => [2016-05-01 09:55:00 +0300, 2016-05-02 09:55:00 +0300, 2016-05-03 09:55:00 +0300]
+```
+
 See also [Sequence YARD docs](http://www.rubydoc.info/gems/time_math2/TimeMath/Sequence).
 
 ### Measuring time periods
 
-Simple measure: just "how many `<unit>`s from date A to date B:
+Simple measure: just "how many `<unit>`s from date A to date B":
 
 ```ruby
 TimeMath.week.measure(Time.parse('2016-05-01'), Time.parse('2016-06-01'))
@@ -181,23 +247,53 @@ TimeMath.measure(birthday, Time.now, upto: :day)
 # => {:days=>12157, :hours=>2, :minutes=>26, :seconds=>55}
 ```
 
-### Optional `Time` and `DateTime` patches
+### Resampling
+
+**Resampling** is useful for situations when you have some timestamped
+data (with variable holes between values), and wantto make it regular,
+e.g. for charts drawing.
+
+The most simple (and not very useful) resampling just turns array of
+irregular timestamps into regular one:
+
+```ruby
+dates = %w[2016-06-01 2016-06-03 2016-06-06].map(&Date.method(:parse))
+# => [#<Date: 2016-06-01>, #<Date: 2016-06-03>, #<Date: 2016-06-06>]
+TimeMath.day.resample(dates)
+# => [#<Date: 2016-06-01>, #<Date: 2016-06-02>, #<Date: 2016-06-03>, #<Date: 2016-06-04>, #<Date: 2016-06-05>, #<Date: 2016-06-06>]
+TimeMath.week.resample(dates)
+# => [#<Date: 2016-05-30>, #<Date: 2016-06-06>]
+TimeMath.month.resample(dates)
+# => [#<Date: 2016-06-01>]
+```
 
-This core classes extension is optional and should be required explicitly.
-TimeMath doesn't change behavior of any existing methods (like `#+`),
-it just adds a couple of new ones:
+Much more useful is _hash resampling_: when you have a hash of `{timestamp => value}`
+and...
 
 ```ruby
-require 'time_math/core_ext'
+data = {Date.parse('2016-06-01') => 18, Date.parse('2016-06-03') => 8, Date.parse('2016-06-06') => -4}
+# => {#<Date: 2016-06-01>=>18, #<Date: 2016-06-03>=>8, #<Date: 2016-06-06>=>-4}
+TimeMath.day.resample(data)
+# => {#<Date: 2016-06-01>=>[18], #<Date: 2016-06-02>=>[], #<Date: 2016-06-03>=>[8], #<Date: 2016-06-04>=>[], #<Date: 2016-06-05>=>[], #<Date: 2016-06-06>=>[-4]}
+TimeMath.week.resample(data)
+# => {#<Date: 2016-05-30>=>[18, 8], #<Date: 2016-06-06>=>[-4]}
+TimeMath.month.resample(data)
+# => {#<Date: 2016-06-01>=>[18, 8, -4]}
+```
+
+For values grouping strategy, `resample` accepts symbol and block arguments:
 
-Time.now.decrease_by(:day, 10).floor_to(:month)
-Time.now.sequence_to(:month, Time.now.advance_by(:year, 5))
+```ruby
+TimeMath.week.resample(data, :first)
+# => {#<Date: 2016-05-30>=>18, #<Date: 2016-06-06>=>-4}
+TimeMath.week.resample(data) { |vals| vals.inject(:+) }
+ => {#<Date: 2016-05-30>=>26, #<Date: 2016-06-06>=>-4}
 ```
 
-See [CoreExt](http://www.rubydoc.info/gems/time_math2/TimeMath/CoreExt)
-documentation for full lists of methods added.
+The functionality currently considered experimental, please notify me
+about your ideas and use cases via [GitHub issues](https://github.com/zverok/time_math2/issues)!
 
-### Notes on timezones
+## Notes on timezones
 
 TimeMath tries its best to preserve timezones of original values. Currently,
 it means:
@@ -208,19 +304,18 @@ it means:
   it is preserved by TimeMath (but be careful about jumping around DST,
   offset would not change).
 
-## Got it, what else?
+## Compatibility notes
 
-TimeMath also play well when included into other classes or modules:
+TimeMath is known to work on MRI Ruby >= 1.9.
 
-```ruby
-class MyModel
-  include TimeMath
+On JRuby it works, too, though there could be _slightly_ unexpected results,
+when JRuby fails to create time by timezone name (see [bug](https://github.com/jruby/jruby/issues/3978)).
+TimeMath in this case fallbacks to the same solution that used for `DateTime`,
+and at least preserves utc offset.
 
-  def next_day
-    day.advance # Here!
-  end
-end
-```
+On Rubinius, some of tests fail and I haven't time to investigate it. If
+somebody still uses Rubinius and wants TimeMath to be working properly
+on it, please let me know.
 
 ## Alternatives
 

data/lib/time_math.rb

@@ -1,10 +1,5 @@
 require 'time'
 
-require_relative './time_math/units'
-require_relative './time_math/sequence'
-require_relative './time_math/measure'
-require_relative './time_math/span'
-
 # TimeMath is a small library for easy time units arithmetics (like "floor
 # the timestamp to the nearest hour", "advance the time value by 3 days"
 # and so on).
@@ -21,10 +16,18 @@ require_relative './time_math/span'
 # time unit, which incapsulates most of the functionality. Refer to
 # {Units::Base} to see what you can get of it.
 #
+# See also `TimeMath()` method in global namespace, it is lot of fun!
+#
 module TimeMath
-  # rubocop:disable Style/ModuleFunction
-  extend self
-  # rubocop:enable Style/ModuleFunction
+  require_relative './time_math/backports'
+  require_relative './time_math/units'
+  require_relative './time_math/op'
+  require_relative './time_math/sequence'
+  require_relative './time_math/measure'
+  require_relative './time_math/resamplers'
+  require_relative './time_math/util'
+
+  module_function
 
   # List all unit names known.
   #
@@ -71,7 +74,7 @@ module TimeMath
   #   @return [Units::Base]
   #
   Units.names.each do |unit|
-    define_method(unit) { Units.get(unit) }
+    define_singleton_method(unit) { Units.get(unit) }
   end
 
   # Measures distance between two time values in all units at once.
@@ -85,8 +88,8 @@ module TimeMath
   # # => {:years=>33, :months=>3, :weeks=>2, :days=>0, :hours=>1, :minutes=>25, :seconds=>52}
   # ```
   #
-  # @param from [Time,DateTime]
-  # @param to [Time,DateTime]
+  # @param from [Time,Date,DateTime]
+  # @param to [Time,Date,DateTime]
   # @param options [Hash] options
   # @option options [Boolean] :weeks pass `false` to exclude weeks from calculation;
   # @option options [Symbol] :upto pass max unit to use (e.g. if you'll
@@ -97,3 +100,39 @@ module TimeMath
     Measure.measure(from, to, options)
   end
 end
+
+# This method helps to create time arithmetics sequence as a value object.
+# Some examples:
+#
+# ```ruby
+# # 10 am at first weekday? Easy!
+# TimeMath(Time.now).floor(:week).advance(:hour, 10).call
+# # => 2016-06-20 10:00:00 +0300
+#
+# # For several time values? Nothing easier!
+# TimeMath(Time.local(2016,1,1), Time.local(2016,2,1), Time.local(2016,3,1)).floor(:week).advance(:hour, 10).call
+# # => [2015-12-28 10:00:00 +0200, 2016-02-01 10:00:00 +0200, 2016-02-29 10:00:00 +0200]
+#
+# # Or, the most fun, you can create complicated operation and call it
+# # later:
+# op = TimeMath().floor(:week).advance(:hour, 10)
+# # => #<TimeMath::Op floor(:week).advance(:hour, 10)>
+# op.call(Time.now)
+# # => 2016-06-20 10:00:00 +0300
+#
+# # or even as a lambda:
+# times = [Time.local(2016,1,1), Time.local(2016,2,1), Time.local(2016,3,1)]
+# times.map(&op)
+# # => [2015-12-28 10:00:00 +0200, 2016-02-01 10:00:00 +0200, 2016-02-29 10:00:00 +0200]
+# ```
+#
+# See also {TimeMath::Op} for list of operations available, but basically
+# they are all same you can call on {TimeMath::Unit}, just pass unit symbol
+# as a first argument.
+#
+# @param arguments time-y value, or list of them, or nothing
+#
+# @return [TimeMath::Op]
+def TimeMath(*arguments) # rubocop:disable Style/MethodName
+  TimeMath::Op.new(*arguments)
+end

data/lib/time_math/backports.rb

@@ -0,0 +1,8 @@
+# @private
+class Array
+  if RUBY_VERSION < '2.1'
+    def to_h
+      Hash[*flatten(1)]
+    end
+  end
+end

data/lib/time_math/op.rb

@@ -0,0 +1,209 @@
+module TimeMath
+  # `Op` is value object, incapsulating several operations performed on
+  # time unit. The names of operations are the same the single unit can
+  # perform, first parameter is always a unit.
+  #
+  # Ops can be created by `TimeMath::Op.new` or with pretty shortcut
+  # `TimeMath()`.
+  #
+  # Available usages:
+  #
+  # ```ruby
+  # # 1. chain operations:
+  # # without Op: 10:25 at first day of next week:
+  # TimeMath.min.advance(TimeMath.hour.advance(TimeMath.week.ceil(tm), 10), 25)
+  # # FOOOOOO
+  # # ...but with Op:
+  # TimeMath(tm).ceil(:week).advance(:hour, 10).advance(:min, 25).call
+  #
+  # # 2. chain operations on multiple objects:
+  # TimeMath(tm1, tm2, tm3).ceil(:week).advance(:hour, 10).advance(:min, 25).call
+  # # or
+  # TimeMath([array_of_times]).ceil(:week).advance(:hour, 10).advance(:min, 25).call
+  #
+  # # 3. preparing operation to be used on any objects:
+  # op = TimeMath().ceil(:week).advance(:hour, 10).advance(:min, 25)
+  # op.call(tm)
+  # op.call(tm1, tm2, tm3)
+  # op.call(array_of_times)
+  # # or even block-ish behavior:
+  # [tm1, tm2, tm3].map(&op)
+  # ```
+  #
+  # Note that Op also plays well with {Sequence} (see its docs for more).
+  class Op
+    # @private
+    OPERATIONS = [:floor, :ceil, :round, :next, :prev, :advance, :decrease].freeze
+
+    attr_reader :operations, :arguments
+
+    # Creates Op. Could (and recommended be also by its alias -- just
+    # `TimeMath(*arguments)`.
+    #
+    # @param arguments one, or several, or an array of time-y values
+    #   (Time, Date, DateTime).
+    def initialize(*arguments)
+      @arguments = arguments
+      @operations = []
+    end
+
+    # @private
+    def initialize_copy(other)
+      @arguments = other.arguments.dup
+      @operations = other.operations.dup
+    end
+
+    # @method floor!(unit, span = 1)
+    #   Adds {Units::Base#floor} to list of operations.
+    #
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param span [Numeric] how many units to floor to.
+    #   @return [self]
+    #
+    # @method floor(unit, span = 1)
+    #   Non-destructive version of {#floor!}.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param span [Numeric] how many units to floor to.
+    #   @return [Op]
+    #
+    # @method ceil!(unit, span = 1)
+    #   Adds {Units::Base#ceil} to list of operations.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param span [Numeric] how many units to ceil to.
+    #   @return [self]
+    #
+    # @method ceil(unit, span = 1)
+    #   Non-destructive version of {#ceil!}.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param span [Numeric] how many units to ceil to.
+    #   @return [Op]
+    #
+    # @method round!(unit, span = 1)
+    #   Adds {Units::Base#round} to list of operations.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param span [Numeric] how many units to round to.
+    #   @return [self]
+    #
+    # @method round(unit, span = 1)
+    #   Non-destructive version of {#round!}.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param span [Numeric] how many units to round to.
+    #   @return [Op]
+    #
+    # @method next!(unit, span = 1)
+    #   Adds {Units::Base#next} to list of operations.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param span [Numeric] how many units to ceil to.
+    #   @return [self]
+    #
+    # @method next(unit, span = 1)
+    #   Non-destructive version of {#next!}.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param span [Numeric] how many units to ceil to.
+    #   @return [Op]
+    #
+    # @method prev!(unit, span = 1)
+    #   Adds {Units::Base#prev} to list of operations.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param span [Numeric] how many units to floor to.
+    #   @return [self]
+    #
+    # @method prev(unit, span = 1)
+    #   Non-destructive version of {#prev!}.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param span [Numeric] how many units to floor to.
+    #   @return [Op]
+    #
+    # @method advance!(unit, amount = 1)
+    #   Adds {Units::Base#advance} to list of operations.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param amount [Numeric] how many units to advance.
+    #   @return [self]
+    #
+    # @method advance(unit, amount = 1)
+    #   Non-destructive version of {#advance!}.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param amount [Numeric] how many units to advance.
+    #   @return [Op]
+    #
+    # @method decrease!(unit, amount = 1)
+    #   Adds {Units::Base#decrease} to list of operations.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param amount [Numeric] how many units to decrease.
+    #   @return [self]
+    #
+    # @method decrease(unit, amount = 1)
+    #   Non-destructive version of {#decrease!}.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param amount [Numeric] how many units to decrease.
+    #   @return [Op]
+    #
+
+    OPERATIONS.each do |op|
+      define_method "#{op}!" do |unit, *args|
+        Units.names.include?(unit) or raise(ArgumentError, "Unknown unit #{unit}")
+        @operations << [op, unit, args]
+        self
+      end
+
+      define_method op do |unit, *args|
+        dup.send("#{op}!", unit, *args)
+      end
+    end
+
+    def inspect
+      "#<#{self.class}#{inspect_args}" + inspect_operations + '>'
+    end
+
+    # @private
+    def inspect_operations
+      operations.map { |op, unit, args|
+        "#{op}(#{[unit, *args].map(&:inspect).join(', ')})"
+      }.join('.')
+    end
+
+    def ==(other)
+      self.class == other.class && operations == other.operations &&
+        arguments == other.arguments
+    end
+
+    # Performs op. If an Op was created with arguments, just performs all
+    # operations on them and returns the result. If it was created without
+    # arguments, performs all operations on arguments provided to `call`.
+    #
+    # @param tms one, or several, or an array of time-y values; should not
+    #   be passed if Op was created with arguments.
+    # @return [Time,Date,DateTime,Array] one, or an array of processed arguments
+    def call(*tms)
+      unless @arguments.empty?
+        tms.empty? or raise(ArgumentError, 'Op arguments is already set, use call()')
+        tms = @arguments
+      end
+      res = [*tms].flatten.map(&method(:perform))
+      tms.count == 1 && Util.timey?(tms.first) ? res.first : res
+    end
+
+    # Allows to use Op as a block:
+    #
+    # ```ruby
+    # timestamps.map(&TimeMath().ceil(:week).advance(:day, 1))
+    # ```
+    # @return [Proc]
+    def to_proc
+      method(:call).to_proc
+    end
+
+    private
+
+    def inspect_args
+      return ' ' if @arguments.empty?
+      '(' + [*@arguments].map(&:inspect).join(', ') + ').'
+    end
+
+    def perform(tm)
+      operations.inject(tm) { |memo, (op, unit, args)|
+        TimeMath::Units.get(unit).send(op, memo, *args)
+      }
+    end
+  end
+end