time_math2 0.0.4 → 0.0.5

data/lib/time_math/resamplers.rb

@@ -0,0 +1,76 @@
+module TimeMath
+  # @private
+  class Resampler
+    class << self
+      def call(name, array_or_hash, symbol = nil, &block)
+        if array_or_hash.is_a?(Array) && array_or_hash.all?(&Util.method(:timey?))
+          ArrayResampler.new(name, array_or_hash).call
+        elsif array_or_hash.is_a?(Hash) && array_or_hash.keys.all?(&Util.method(:timey?))
+          HashResampler.new(name, array_or_hash).call(symbol, &block)
+        else
+          raise ArgumentError, "Array of timestamps or hash with timestamp keys, #{array_or_hash} got"
+        end
+      end
+    end
+
+    def initialize(unit)
+      @unit = Units.get(unit)
+    end
+
+    private
+
+    def sequence
+      @sequence ||= @unit.sequence(from...to, expand: true)
+    end
+
+    def from
+      timestamps.min
+    end
+
+    def to
+      @unit.next(timestamps.max)
+    end
+  end
+
+  # @private
+  class ArrayResampler < Resampler
+    def initialize(unit, array)
+      super(unit)
+      @array = array
+    end
+
+    def call
+      sequence.to_a
+    end
+
+    private
+
+    def timestamps
+      @array
+    end
+  end
+
+  # @private
+  class HashResampler < Resampler
+    def initialize(unit, hash)
+      super(unit)
+      @hash = hash
+    end
+
+    def call(symbol = nil, &block)
+      block = symbol.to_proc if symbol && !block
+
+      sequence.ranges.map do |r|
+        values = @hash.select { |k, _| r.cover?(k) }.map(&:last)
+        values = block.call(values) if block # rubocop:disable Performance/RedundantBlockCall
+        [r.begin, values]
+      end.to_h
+    end
+
+    private
+
+    def timestamps
+      @hash.keys
+    end
+  end
+end

data/lib/time_math/sequence.rb

@@ -8,27 +8,18 @@ module TimeMath
   # ```ruby
   # from = Time.parse('2016-05-01 13:30')
   # to = Time.parse('2016-05-04 18:20')
-  # seq = TimeMath.day.sequence(from, to)
-  # # => #<TimeMath::Sequence(2016-05-01 13:30:00 +0300 - 2016-05-04 18:20:00 +0300)>
+  # seq = TimeMath.day.sequence(from...to)
+  # # => #<TimeMath::Sequence(2016-05-01 13:30:00 +0300...2016-05-04 18:20:00 +0300)>
   # ```
   #
   # Now, you can use it:
+  #
   # ```ruby
   # seq.to_a
   # # => [2016-05-01 13:30:00 +0300, 2016-05-02 13:30:00 +0300, 2016-05-03 13:30:00 +0300, 2016-05-04 13:30:00 +0300]
   # ```
   # -- it's an "each day start between from and to". As you can see,
-  # the period start is the same as in `from`. You can request to floor
-  # them to beginning of day with {#floor} method or `:floor` option:
-  #
-  # ```ruby
-  # seq.floor.to_a
-  # # => [2016-05-01 13:30:00 +0300, 2016-05-02 00:00:00 +0300, 2016-05-03 00:00:00 +0300, 2016-05-04 00:00:00 +0300]
-  # # or:
-  # seq = TimeMath.day.sequence(from, to, floor: true)
-  # seq.to_a
-  # ```
-  # -- it floors all day starts except of `from`, which is preserved.
+  # the period start is the same as in `from`.
   #
   # You can expand from and to to nearest round unit by {#expand} method
   # or `:expand` option:
@@ -37,16 +28,23 @@ module TimeMath
   # seq.expand.to_a
   # # => [2016-05-01 00:00:00 +0300, 2016-05-02 00:00:00 +0300, 2016-05-03 00:00:00 +0300, 2016-05-04 00:00:00 +0300]
   # # or:
-  # seq = TimeMath.day.sequence(from, to, expand: true)
-  # # => #<TimeMath::Sequence(2016-05-01 00:00:00 +0300 - 2016-05-05 00:00:00 +0300)>
+  # seq = TimeMath.day.sequence(from...to, expand: true)
+  # # => #<TimeMath::Sequence(2016-05-01 00:00:00 +0300...2016-05-05 00:00:00 +0300)>
+  # seq.to_a
+  # # => [2016-05-01 00:00:00 +0300, 2016-05-02 00:00:00 +0300, 2016-05-03 00:00:00 +0300, 2016-05-04 00:00:00 +0300]
+  # # ^ note that `to` is excluded.
+  # # You can include it by creating sequence from including-end range:
+  # seq = TimeMath.day.sequence(from..to, expand: true)
+  # # => #<TimeMath::Sequence(:day, 2016-05-01 00:00:00 +0300..2016-05-05 00:00:00 +0300)>
   # seq.to_a
+  # # => [2016-05-01 00:00:00 +0300, 2016-05-02 00:00:00 +0300, 2016-05-03 00:00:00 +0300, 2016-05-04 00:00:00 +0300, 2016-05-05 00:00:00 +0300]
   # ```
   #
   # Besides each period beginning, you can also request pairs of begin/end
   # of a period, either as an array of arrays, or array of ranges:
   #
   # ```ruby
-  # seq = TimeMath.day.sequence(from, to)
+  # seq = TimeMath.day.sequence(from...to)
   # seq.pairs
   # # => [[2016-05-01 13:30:00 +0300, 2016-05-02 13:30:00 +0300], [2016-05-02 13:30:00 +0300, 2016-05-03 13:30:00 +0300], [2016-05-03 13:30:00 +0300, 2016-05-04 13:30:00 +0300], [2016-05-04 13:30:00 +0300, 2016-05-04 18:20:00 +0300]]
   # seq.ranges
@@ -56,47 +54,71 @@ module TimeMath
   # It is pretty convenient for filtering data from databases or APIs,
   # TimeMath creates list of filtering ranges in a blink.
   #
+  # Sequence also supports any item-updating operations in the same fashion
+  # {Op} does:
+  #
+  # ```ruby
+  # seq = TimeMath.day.sequence(from...to, expand: true).advance(:hour, 5).decrease(:min, 20)
+  # # => #<TimeMath::Sequence(:day, 2016-05-01 00:00:00 +0300...2016-05-05 00:00:00 +0300).advance(:hour, 5).decrease(:min, 20)>
+  # seq.to_a
+  # # => [2016-05-01 04:40:00 +0300, 2016-05-02 04:40:00 +0300, 2016-05-03 04:40:00 +0300, 2016-05-04 04:40:00 +0300]
+  # ```
+  #
   class Sequence
     # Creates a sequence. Typically, it is easier to to it with {Units::Base#sequence},
     # like this:
     #
     # ```ruby
-    # TimeMath.day.sequence(from, to)
+    # TimeMath.day.sequence(from...to)
     # ```
     #
     # @param unit [Symbol] one of {TimeMath.units};
-    # @param from [Time,DateTime] start of sequence;
-    # @param to [Time,DateTime] upper limit of sequence;
+    # @param range [Range] range of time-y values (Time, Date, DateTime);
+    #   note that range with inclusive and exclusive and will produce
+    #   different sequences.
     # @param options [Hash]
     # @option options [Boolean] :expand round sequence ends on creation
-    #   (from is floored and to is ceiled);
-    # @option options [Boolean] :floor sequence will be rounding'ing all
-    #   the intermediate values.
+    #   (`from` is floored and `to` is ceiled);
     #
-    def initialize(unit, from, to, options = {})
+    def initialize(unit, range, options = {})
       @unit = Units.get(unit)
-      @from, @to = from, to
+      @from, @to, @exclude_end = process_range(range)
       @options = options.dup
 
       expand! if options[:expand]
-      @floor = options[:floor]
+      @op = Op.new
+    end
+
+    # @private
+    def initialize_copy(other)
+      @unit = other.unit
+      @from, @to, @exclude_end = other.from, other.to, other.exclude_end?
+      @op = other.op.dup
     end
 
-    attr_reader :from, :to, :unit
+    attr_reader :from, :to, :unit, :op
 
-    def ==(other)
+    # Compares two sequences, considering their start, end, unit and
+    # operations.
+    #
+    # @param other [Sequence]
+    # @return [Boolean]
+    def ==(other) # rubocop:disable Metrics/AbcSize
       self.class == other.class && unit == other.unit &&
-        from == other.from && to == other.to
+        from == other.from && to == other.to &&
+        exclude_end? == other.exclude_end? &&
+        op == other.op
     end
 
-    # If `:floor` option is set for sequence.
-    def floor?
-      @floor
+    # Whether sequence was created from exclude-end range (and, therefore,
+    # will exclude `to` when converted to array).
+    def exclude_end?
+      @exclude_end
     end
 
     # Expand sequence ends to nearest round unit.
     #
-    # @return self
+    # @return [self]
     def expand!
       @from = unit.floor(from)
       @to = unit.ceil(to)
@@ -108,22 +130,104 @@ module TimeMath
     #
     # @return [Sequence]
     def expand
-      dup.tap(&:expand!)
+      dup.expand!
     end
 
-    # Sets sequence to floor all the intermediate values.
+    # @method floor!(unit, span = 1)
+    #   Adds {Units::Base#floor} to list of operations to apply to sequence items.
     #
-    # @return self
-    def floor!
-      @floor = true
-    end
-
-    # Creates new sequence with setting to floor all the intermediate
-    # values.
+    #   @param unit [Symbol] One of {TimeMath.units}
+    #   @param span [Numeric] how many units to floor to.
+    #   @return [self]
     #
-    # @return [Sequence]
-    def floor
-      dup.tap(&:floor!)
+    # @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 [Sequence]
+    #
+    # @method ceil!(unit, span = 1)
+    #   Adds {Units::Base#ceil} to list of operations to apply to sequence items.
+    #   @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 [Sequence]
+    #
+    # @method round!(unit, span = 1)
+    #   Adds {Units::Base#round} to list of operations to apply to sequence items.
+    #   @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 [Sequence]
+    #
+    # @method next!(unit, span = 1)
+    #   Adds {Units::Base#next} to list of operations to apply to sequence items.
+    #   @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 [Sequence]
+    #
+    # @method prev!(unit, span = 1)
+    #   Adds {Units::Base#prev} to list of operations to apply to sequence items.
+    #   @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 [Sequence]
+    #
+    # @method advance!(unit, amount = 1)
+    #   Adds {Units::Base#advance} to list of operations to apply to sequence items.
+    #   @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 [Sequence]
+    #
+    # @method decrease!(unit, amount = 1)
+    #   Adds {Units::Base#decrease} to list of operations to apply to sequence items.
+    #   @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 [Sequence]
+    #
+
+    Op::OPERATIONS.each do |operation|
+      define_method "#{operation}!" do |*arg|
+        @op.send("#{operation}!", *arg)
+        self
+      end
+
+      define_method operation do |*arg|
+        dup.send("#{operation}!", *arg)
+      end
     end
 
     # Creates an array of time unit starts between from and to. They will
@@ -139,10 +243,11 @@ module TimeMath
       while iter < to
         seq << iter
 
-        iter = cond_floor(unit.advance(iter))
+        iter = unit.advance(iter)
       end
+      seq << to unless exclude_end?
 
-      seq
+      op.call(seq)
     end
 
     # Creates an array of pairs (time unit start, time unit end) between
@@ -163,13 +268,18 @@ module TimeMath
     end
 
     def inspect
-      "#<#{self.class}(#{from} - #{to})>"
+      ops = op.inspect_operations
+      ops = '.' + ops unless ops.empty?
+      "#<#{self.class}(#{unit.name.inspect}, #{from}#{exclude_end? ? '...' : '..'}#{to})#{ops}>"
     end
 
     private
 
-    def cond_floor(tm)
-      @floor ? unit.floor(tm) : tm
+    def process_range(range)
+      range.is_a?(Range) && Util.timey?(range.begin) && Util.timey?(range.end) or
+        raise ArgumentError, "Range of time-y values expected, #{range} got"
+
+      [range.begin, range.end, range.exclude_end?]
     end
   end
 end

data/lib/time_math/units/base.rb

@@ -8,6 +8,13 @@ module TimeMath
     # TimeMath.day.advance(tm, 5) # advances tm by 5 days
     # ```
     #
+    # See also {TimeMath::Op} for performing multiple operations in
+    # concise & DRY manner, like this:
+    #
+    # ```ruby
+    # TimeMath().advance(:day, 5).floor(:hour).advance(:min, 20).call(tm)
+    # ```
+    #
     class Base
       # Creates unit of time. Typically you don't need it, as it is
       # easier to do `TimeMath.day` or `TimeMath[:day]` to obtain it.
@@ -22,41 +29,59 @@ module TimeMath
       # Rounds `tm` down to nearest unit (this means, `TimeMath.day.floor(tm)`
       # will return beginning of `tm`-s day, and so on).
       #
-      # @param tm [Time,DateTime] time value to floor.
-      # @return [Time,DateTime] floored time value; class and timezone info
-      #   of origin would be preserved.
-      def floor(tm)
-        components = [tm.year,
-                      tm.month,
-                      tm.day,
-                      tm.hour,
-                      tm.min,
-                      tm.sec].first(index + 1)
-
-        new_from_components(tm, *components)
+      # An optional second argument allows you to floor to arbitrary
+      # number of units, like to "each 3-hour" mark:
+      #
+      # ```ruby
+      # TimeMath.hour.floor(Time.parse('14:00'), 3)
+      # # => 2016-06-23 12:00:00 +0300
+      #
+      # # works well with float/rational spans
+      # TimeMath.hour.floor(Time.parse('14:15'), 1/2r)
+      # # => 2016-06-23 14:00:00 +0300
+      # TimeMath.hour.floor(Time.parse('14:45'), 1/2r)
+      # # => 2016-06-23 14:30:00 +0300
+      # ```
+      #
+      # @param tm [Time,Date,DateTime] time value to floor.
+      # @param span [Numeric] how many units to floor to. For units
+      #   less than week supports float/rational values.
+      # @return [Time,Date,DateTime] floored time value; class and timezone
+      #   info of origin would be preserved.
+      def floor(tm, span = 1)
+        int_floor = advance(floor_1(tm), (tm.send(name) / span.to_f).floor * span - tm.send(name))
+        float_fix(tm, int_floor, span % 1)
       end
 
       # Rounds `tm` up to nearest unit (this means, `TimeMath.day.ceil(tm)`
       # will return beginning of day next after `tm`, and so on).
+      # An optional second argument allows to ceil to arbitrary
+      # amount of units (see {#floor} for more detailed explanation).
       #
-      # @param tm [Time,DateTime] time value to ceil.
-      # @return [Time,DateTime] ceiled time value; class and timezone info
+      # @param tm [Time,Date,DateTime] time value to ceil.
+      # @param span [Numeric] how many units to ceil to. For units
+      #   less than week supports float/rational values.
+      # @return [Time,Date,DateTime] ceiled time value; class and timezone info
       #   of origin would be preserved.
-      def ceil(tm)
-        f = floor(tm)
+      def ceil(tm, span = 1)
+        f = floor(tm, span)
 
-        f == tm ? f : advance(f)
+        f == tm ? f : advance(f, span)
       end
 
       # Rounds `tm` up or down to nearest unit (this means, `TimeMath.day.round(tm)`
       # will return beginning of `tm` day if `tm` is before noon, and
       # day next after `tm` if it is after, and so on).
+      # An optional second argument allows to round to arbitrary
+      # amount of units (see {#floor} for more detailed explanation).
       #
-      # @param tm [Time,DateTime] time value to round.
-      # @return [Time,DateTime] rounded time value; class and timezone info
+      # @param tm [Time,Date,DateTime] time value to round.
+      # @param span [Numeric] how many units to round to. For units
+      #   less than week supports float/rational values.
+      # @return [Time,Date,DateTime] rounded time value; class and timezone info
       #   of origin would be preserved.
-      def round(tm)
-        f, c = floor(tm), ceil(tm)
+      def round(tm, span = 1)
+        f, c = floor(tm, span), ceil(tm, span)
 
         (tm - f).abs < (tm - c).abs ? f : c
       end
@@ -64,41 +89,52 @@ module TimeMath
       # Like {#floor}, but always return value lower than `tm` (e.g. if
       # `tm` is exactly midnight, then `TimeMath.day.prev(tm)` will return
       # _previous midnight_).
+      # An optional second argument allows to floor to arbitrary
+      # amount of units (see {#floor} for more detailed explanation).
       #
-      # @param tm [Time,DateTime] time value to calculate prev on.
-      # @return [Time,DateTime] prev time value; class and timezone info
+      # @param tm [Time,Date,DateTime] time value to calculate prev on.
+      # @param span [Numeric] how many units to floor to. For units
+      #   less than week supports float/rational values.
+      # @return [Time,Date,DateTime] prev time value; class and timezone info
       #   of origin would be preserved.
-      def prev(tm)
-        f = floor(tm)
-        f == tm ? decrease(f) : f
+      def prev(tm, span = 1)
+        f = floor(tm, span)
+        f == tm ? decrease(f, span) : f
       end
 
       # Like {#ceil}, but always return value greater than `tm` (e.g. if
       # `tm` is exactly midnight, then `TimeMath.day.next(tm)` will return
       # _next midnight_).
+      # An optional second argument allows to ceil to arbitrary
+      # amount of units (see {#floor} for more detailed explanation).
       #
-      # @param tm [Time,DateTime] time value to calculate next on.
-      # @return [Time,DateTime] next time value; class and timezone info
+      # @param tm [Time,Date,DateTime] time value to calculate next on.
+      # @param span [Numeric] how many units to ceil to. For units
+      #   less than week supports float/rational values.
+      # @return [Time,Date,DateTime] next time value; class and timezone info
       #   of origin would be preserved.
-      def next(tm)
-        c = ceil(tm)
-        c == tm ? advance(c) : c
+      def next(tm, span = 1)
+        c = ceil(tm, span)
+        c == tm ? advance(c, span) : c
       end
 
       # Checks if `tm` is exactly rounded to unit.
       #
-      # @param tm [Time,DateTime] time value to check.
+      # @param tm [Time,Date,DateTime] time value to check.
+      # @param span [Numeric] how many units to check round at. For units
+      #   less than week supports float/rational values.
       # @return [Boolean] whether `tm` is exactly round to unit.
-      def round?(tm)
-        floor(tm) == tm
+      def round?(tm, span = 1)
+        floor(tm, span) == tm
       end
 
       # Advances `tm` by given amount of unit.
       #
-      # @param tm [Time,DateTime] time value to advance;
-      # @param amount [Integer] how many units forward to go.
+      # @param tm [Time,Date,DateTime] time value to advance;
+      # @param amount [Numeric] how many units forward to go. For units
+      #   less than week supports float/rational values.
       #
-      # @return [Time,DateTime] advanced time value; class and timezone info
+      # @return [Time,Date,DateTime] advanced time value; class and timezone info
       #   of origin would be preserved.
       def advance(tm, amount = 1)
         return decrease(tm, -amount) if amount < 0
@@ -107,10 +143,11 @@ module TimeMath
 
       # Decreases `tm` by given amount of unit.
       #
-      # @param tm [Time,DateTime] time value to decrease;
-      # @param amount [Integer] how many units forward to go.
+      # @param tm [Time,Date,DateTime] time value to decrease;
+      # @param amount [Integer] how many units forward to go. For units
+      #   less than week supports float/rational values.
       #
-      # @return [Time,DateTime] decrease time value; class and timezone info
+      # @return [Time,Date,DateTime] decrease time value; class and timezone info
       #   of origin would be preserved.
       def decrease(tm, amount = 1)
         return advance(tm, -amount) if amount < 0
@@ -125,7 +162,7 @@ module TimeMath
       # # => 2016-05-28 16:30:00 +0300...2016-06-02 16:30:00 +0300
       # ```
       #
-      # @param tm [Time,DateTime] time value to create range from;
+      # @param tm [Time,Date,DateTime] time value to create range from;
       # @param amount [Integer] how many units should be between range
       #   start and end.
       #
@@ -142,7 +179,7 @@ module TimeMath
       # # => 2016-05-23 16:30:00 +0300...2016-05-28 16:30:00 +0300
       # ```
       #
-      # @param tm [Time,DateTime] time value to create range from;
+      # @param tm [Time,Date,DateTime] time value to create range from;
       # @param amount [Integer] how many units should be between range
       #   start and end.
       #
@@ -153,8 +190,8 @@ module TimeMath
 
       # Measures distance between `from` and `to` in units of this class.
       #
-      # @param from [Time,DateTime] start of period;
-      # @param to [Time,DateTime] end of period.
+      # @param from [Time,Date,DateTime] start of period;
+      # @param to [Time,Date,DateTime] end of period.
       #
       # @return [Integer] how many full units are inside the period.
       # :nocov:
@@ -175,8 +212,8 @@ module TimeMath
       # # => [26, 2016-05-27 16:20:00 +0300]
       # ```
       #
-      # @param from [Time,DateTime] start of period;
-      # @param to [Time,DateTime] end of period.
+      # @param from [Time,Date,DateTime] start of period;
+      # @param to [Time,Date,DateTime] end of period.
       #
       # @return [Array<Integer, Time or DateTime>] how many full units
       #   are inside the period; exact value of `from` + full units.
@@ -185,30 +222,12 @@ module TimeMath
         [m, advance(from, m)]
       end
 
-      # Creates {Span} instance representing amount of units.
-      #
-      # Use it like this:
-      #
-      # ```ruby
-      # span = TimeMath.day.span(5) # => #<TimeMath::Span(day): +5>
-      # # now you can save this variable or path it to the methods...
-      # # and then:
-      # span.before(Time.parse('2016-05-01')) # => 2016-04-26 00:00:00 +0300
-      # span.after(Time.parse('2016-05-01')) # => 2016-05-06 00:00:00 +0300
-      # ```
-      #
-      # @param amount [Integer]
-      # @return [Span]
-      def span(amount = 1)
-        TimeMath::Span.new(name, amount)
-      end
-
       # Creates {Sequence} instance for producing all time units between
       # from and too. See {Sequence} class documentation for available
       # options and functionality.
       #
-      # @param from [Time,DateTime] start of sequence;
-      # @param to [Time,DateTime] upper limit of sequence;
+      # @param from [Time,Date,DateTime] start of sequence;
+      # @param to [Time,Date,DateTime] upper limit of sequence;
       # @param options [Hash]
       # @option options [Boolean] :expand round sequence ends on creation
       #   (from is floored and to is ceiled);
@@ -216,8 +235,65 @@ module TimeMath
       #   the intermediate values.
       #
       # @return [Sequence]
-      def sequence(from, to, options = {})
-        TimeMath::Sequence.new(name, from, to, options)
+      def sequence(range, options = {})
+        TimeMath::Sequence.new(name, range, options)
+      end
+
+      # Converts input timestamps list to regular list of timestamps
+      # over current unit.
+      #
+      # Like this:
+      #
+      # ```ruby
+      # times = [Time.parse('2016-05-01'), Time.parse('2016-05-03'), Time.parse('2016-05-08')]
+      # TimeMath.day.resample(times)
+      # # =>  => [2016-05-01 00:00:00 +0300, 2016-05-02 00:00:00 +0300, 2016-05-03 00:00:00 +0300, 2016-05-04 00:00:00 +0300, 2016-05-05 00:00:00 +0300, 2016-05-06 00:00:00 +0300, 2016-05-07 00:00:00 +0300, 2016-05-08 00:00:00 +0300]
+      # ```
+      #
+      # The best way about resampling it also works for hashes with time
+      # keys. Like this:
+      #
+      # ```ruby
+      # h = {Date.parse('Wed, 01 Jun 2016')=>1, Date.parse('Tue, 07 Jun 2016')=>3, Date.parse('Thu, 09 Jun 2016')=>1}
+      # # => {#<Date: 2016-06-01>=>1, #<Date: 2016-06-07>=>3, #<Date: 2016-06-09>=>1}
+      #
+      # pp TimeMath.day.resample(h)
+      # # {#<Date: 2016-06-01>=>[1],
+      # #  #<Date: 2016-06-02>=>[],
+      # #  #<Date: 2016-06-03>=>[],
+      # #  #<Date: 2016-06-04>=>[],
+      # #  #<Date: 2016-06-05>=>[],
+      # #  #<Date: 2016-06-06>=>[],
+      # #  #<Date: 2016-06-07>=>[3],
+      # #  #<Date: 2016-06-08>=>[],
+      # #  #<Date: 2016-06-09>=>[1]}
+      #
+      # # The default resample just groups all related values in arrays
+      # # You can pass block or symbol, to have the values you need:
+      # pp TimeMath.day.resample(h,&:first)
+      # # {#<Date: 2016-06-01>=>1,
+      # #  #<Date: 2016-06-02>=>nil,
+      # #  #<Date: 2016-06-03>=>nil,
+      # #  #<Date: 2016-06-04>=>nil,
+      # #  #<Date: 2016-06-05>=>nil,
+      # #  #<Date: 2016-06-06>=>nil,
+      # #  #<Date: 2016-06-07>=>3,
+      # #  #<Date: 2016-06-08>=>nil,
+      # #  #<Date: 2016-06-09>=>1}
+      # ```
+      #
+      # @param array_or_hash array of time-y values (Time/Date/DateTime)
+      #   or hash with time-y keys.
+      # @param symbol in case of first param being a hash -- method to
+      #   call on key arrays while grouping.
+      # @param block in  case of first param being a hash -- block to
+      #   call on key arrays while grouping.
+      #
+      # @return array or hash spread regular by unit; if first param was
+      #   hash, keys corresponding to each period are grouped into arrays;
+      #   this array could be further processed with block/symbol provided.
+      def resample(array_or_hash, symbol = nil, &block)
+        Resampler.call(name, array_or_hash, symbol, &block)
       end
 
       def inspect
@@ -252,13 +328,51 @@ module TimeMath
         components = EMPTY_VALUES.zip(components).map { |d, c| c || d }
         case origin
         when Time
-          Time.mktime(*components.reverse, nil, nil, nil, origin.zone)
+          res = Time.mktime(*components.reverse, nil, nil, nil, origin.zone)
+          fix_no_zone(res, origin, *components)
         when DateTime
           DateTime.new(*components, origin.zone)
+        when Date
+          Date.new(*components.first(3))
+        else
+          raise ArgumentError, "Expected Time, Date or DateTime, got #{origin.class}"
         end
       end
 
-      include TimeMath # now we can use something like #day inside other units
+      def to_components(tm)
+        case tm
+        when Time, DateTime
+          [tm.year, tm.month, tm.day, tm.hour, tm.min, tm.sec]
+        when Date
+          [tm.year, tm.month, tm.day]
+        else
+          raise ArgumentError, "Expected Time, Date or DateTime, got #{tm.class}"
+        end
+      end
+
+      def floor_1(tm)
+        components = to_components(tm).first(index + 1)
+        new_from_components(tm, *components)
+      end
+
+      def float_fix(tm, floored, float_span_part)
+        if float_span_part.zero?
+          floored
+        else
+          float_floored = advance(floored, float_span_part)
+          float_floored > tm ? floored : float_floored
+        end
+      end
+
+      def fix_no_zone(tm, origin, *components)
+        if origin.zone != 'UTC' && tm.zone == 'UTC'
+          # Fixes things like this one: https://github.com/jruby/jruby/issues/3978
+          # ...by falling back to use of UTC offset instead of timezone abbr
+          Time.new(*components, origin.utc_offset)
+        else
+          tm
+        end
+      end
     end
   end
 end