time_math2 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 006dfa63a22116ad083fd98e2aca4390734bce26
+  data.tar.gz: 028d5e1ca0a36f80840b95aadb675f60497385f5
+SHA512:
+  metadata.gz: 261cbba1b37663d18b456edfb0f0ea7a18dbd7c78c72d4c77d6d20feb664a90f4ca2baaffcaf7493a04181cf37c40a4c3480e2493dd767d4dece3dcdf0271e37
+  data.tar.gz: 2d9beccf3cd5e3a3b4f7a35366ec20576dc770c7570768cc6784b8cfb0bcc139df713ac88ac764ba2eb2eb44b6c4aa070d6c3b1e20626bb5c58540a38eff991b

data/.yardopts

@@ -0,0 +1,2 @@
+--markup=markdown
+--no-private

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# TimeBoots changelog
+
+# 0.0.2 (2016-05-27)
+
+* Add support for `DateTime`.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014-15 Victor 'Zverok' Shepelev
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,316 @@
+# Time Math
+
+[![Gem Version](https://badge.fury.io/rb/time_math2.svg)](http://badge.fury.io/rb/time_math2)
+[![Dependency Status](https://gemnasium.com/zverok/time_math2.svg)](https://gemnasium.com/zverok/time_math2)
+[![Code Climate](https://codeclimate.com/github/zverok/time_math2/badges/gpa.svg)](https://codeclimate.com/github/zverok/time_math2)
+[![Build Status](https://travis-ci.org/zverok/time_math2.svg?branch=master)](https://travis-ci.org/zverok/time_math2)
+[![Coverage Status](https://coveralls.io/repos/zverok/time_math2/badge.svg?branch=master)](https://coveralls.io/r/zverok/time_math2?branch=master)
+
+**TimeMath2** is a small, no-dependencies library attempting to make time
+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.
+
+## Features
+
+* No monkey-patching of core classes (opt-in patching of Time and DateTime
+  provided, though);
+* Works with Time 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.
+
+## Naming
+
+`TimeMath` is the better name I know for the task library does, but
+it is [already taken](https://rubygems.org/gems/time_math). So, with no
+other thoughts I came with the ugly solution.
+
+(BTW, the [previous version](https://github.com/zverok/time_math/blob/e997d7ddd52fc5bce3c77dc3c8022adfc9fe7028/README.md)
+had some dumb "funny" name for gem and all helper classes, and nobody liked it.)
+
+## Reasons
+
+You frequently need to calculate things like "exact midnight of the next
+day", but you don't want to monkey-patch all of your integers, tug in
+5K LOC of ActiveSupport and you like to have things clean and readable.
+
+## Installation
+
+Install it like always:
+
+```
+$ gem install time_math2
+```
+
+or add to your Gemfile
+
+```ruby
+gem 'time_math2'
+```
+
+and `bundle install` it.
+
+## Usage
+
+First, you take time unit you want:
+
+```ruby
+TimeMath[:day] # => #<TimeMath::Units::Day>
+# or
+TimeMath.day # => #<TimeMath::Units::Day>
+
+# List of units supported:
+TimeMath.units
+# => [:sec, :min, :hour, :day, :week, :month, :year]
+```
+
+Then you use this unit for any math you want:
+
+```ruby
+TimeMath.day.floor(Time.now) # => 2016-05-28 00:00:00 +0300
+TimeMath.day.ceil(Time.now) # => 2016-05-29 00:00:00 +0300
+TimeMath.day.advance(Time.now, +10) # => 2016-06-07 14:06:57 +0300
+# ...and so on
+```
+
+### Full list of simple arithmetic methods
+
+* `<unit>.floor(tm)` -- rounds down to nearest `<unit>`;
+* `<unit>.ceil(tm)` -- rounds up to nearest `<unit>`;
+* `<unit>.round(tm)` -- rounds to nearest `<unit>` (up or down);
+* `<unit>.round?(tm)` -- checks if `tm` is already round to `<unit>`;
+* `<unit>.prev(tm)` -- like `floor`, but always decreases:
+    - `2015-06-27 13:30` would be converted to `2015-06-27 00:00` by both
+      `floor` and `prev`, but
+    - `2015-06-27 00:00` would be left intact on `floor`, but would be
+      decreased to `2015-06-26 00:00` by `prev`;
+* `<unit>.next(tm)` -- like `ceil`, but always increases;
+* `<unit>.advance(tm, amount)` -- increases tm by integer amount of `<unit>`s;
+* `<unit>.decrease(tm, amount)` -- decreases tm by integer amount of `<unit>`s;
+* `<unit>.range(tm, amount)` -- creates range of `tm ... tm + amount <units>`;
+* `<unit>.range_back(tm, amount)` -- creates range of `tm - amount <units> ... tm`.
+
+See also [Units::Base](http://www.rubydoc.info/gems/time_math2/TimeMath/Units/Base).
+
+### Time span abstraction
+
+`TimeMath::Span` is a simple abstraction of "N units of time", which you
+can store in variable and then apply to some time value:
+
+```ruby
+span = TimeMath.day.span(5)
+# => #<TimeMath::Span(day): +5>
+span.before(Time.now)
+# => 2016-05-23 17:46:13 +0300
+```
+
+See also [Span YARD docs](http://www.rubydoc.info/gems/time_math2/TimeMath/Span).
+
+### Time sequence abstraction
+
+Time sequence allows you to generate an array of time values between some
+points:
+
+```ruby
+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)>
+p(*seq)
+# 2016-05-28 00:00:00 +0300
+# 2016-05-28 01:00:00 +0300
+# 2016-05-28 02:00:00 +0300
+# 2016-05-28 03:00:00 +0300
+# 2016-05-28 04:00:00 +0300
+# 2016-05-28 05:00:00 +0300
+# 2016-05-28 06:00:00 +0300
+# 2016-05-28 07:00:00 +0300
+# ...and so on
+```
+
+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:
+
+```ruby
+TimeMath.week.measure(Time.parse('2016-05-01'), Time.parse('2016-06-01'))
+# => 4
+```
+
+Measure with remaineder: returns number of `<unit>`s between dates and
+the date when this number would be exact:
+
+```ruby
+TimeMath.week.measure_rem(Time.parse('2016-05-01'), Time.parse('2016-06-01'))
+# => [4, 2016-05-29 00:00:00 +0300]
+```
+
+(on May 29 there would be exactly 4 weeks since May 1).
+
+Multi-unit measuring:
+
+```ruby
+# My real birthday, in fact!
+birthday = Time.parse('1983-02-14 13:30')
+
+# My full age
+TimeMath.measure(birthday, Time.now)
+# => {:years=>33, :months=>3, :weeks=>2, :days=>0, :hours=>1, :minutes=>25, :seconds=>52}
+
+# NB: you can use this output with String#format or String%:
+puts "%{years}y %{months}m %{weeks}w %{days}d %{hours}h %{minutes}m %{seconds}s" %
+  TimeMath.measure(birthday, Time.now)
+# 33y 3m 2w 0d 1h 26m 15s
+
+# Option: measure without weeks
+TimeMath.measure(birthday, Time.now, weeks: false)
+# => {:years=>33, :months=>3, :days=>14, :hours=>1, :minutes=>26, :seconds=>31}
+
+# My full age in days, hours, minutes
+TimeMath.measure(birthday, Time.now, upto: :day)
+# => {:days=>12157, :hours=>2, :minutes=>26, :seconds=>55}
+```
+
+### Optional `Time` and `DateTime` patches
+
+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:
+
+```ruby
+require 'time_math/core_ext'
+
+Time.now.decrease_by(:day, 10).floor_to(:month)
+Time.now.sequence_to(:month, Time.now.advance_by(:year, 5))
+```
+
+See [CoreExt](http://www.rubydoc.info/gems/time_math2/TimeMath/CoreExt)
+documentation for full lists of methods added.
+
+### Notes on timezones
+
+TimeMath tries its best to preserve timezones of original values. Currently,
+it means:
+
+* For `Time` instances, symbolic timezone is preserved; when jumping over
+  DST border, UTC offset will change and everything remains as expected;
+* For `DateTime` Ruby not provides symbolic timezone, only numeric offset;
+  it is preserved by TimeMath (but be careful about jumping around DST,
+  offset would not change).
+
+
+## Time series generation: "laces"
+
+I'm a real fan of funny names in gems. Here we have time **boots** for working
+with time **steps**. So, something continuous will be called **lace**.
+
+I hope, next examples are pretty self-explanatory.
+
+```ruby
+from = Time.parse('2015-03-05 10:08')
+to = Time.parse('2015-03-09 11:07')
+
+lace = TimeBoots.month.lace(from, to)
+# => #<TimeBoots::Lace(2015-03-05 10:08:00 +0200 - 2015-03-09 11:07:00 +0200)>
+
+# or
+TimeBoots.lace(:month, from, to)
+# => #<TimeBoots::Lace(2015-03-05 10:08:00 +0200 - 2015-03-09 11:07:00 +0200)>
+
+lace.pull
+# => [2015-03-05 10:08:00 +0200,
+#     2015-03-06 10:08:00 +0200,
+#     2015-03-07 10:08:00 +0200,
+#     2015-03-08 10:08:00 +0200,
+#     2015-03-09 10:08:00 +0200]
+```
+
+So, we have just a series of times, each day, from `from` until `to`.
+Note, there is a same time of the day (10:08), as it was in `from`.
+
+The `pull` method has an optional argument, when it is `true`, the
+method returns `floor`-ed times (e.g. midnights for daily lace):
+
+```ruby
+lace.pull(true)
+# => [2015-03-05 10:08:00 +0200,
+#     2015-03-06 00:00:00 +0200,
+#     2015-03-07 00:00:00 +0200,
+#     2015-03-08 00:00:00 +0200,
+#     2015-03-09 00:00:00 +0200]
+```
+
+Note the first value still at 10:08: we don't want to go before `from`.
+Lace also can "expand" your period for you (`floor` the beginning and
+`ceil` the end):
+
+```ruby
+lace.expand
+# => #<TimeBoots::Lace(2015-03-05 00:00:00 +0200-2015-03-10 00:00:00 +0200)>
+
+# or
+lace.expand!
+
+# or start with expanded:
+TimeBoots.month.lace(from, to, expanded: true)
+```
+
+Another useful lace's functionality is generating periods.
+It can be useful for filtering daily data from database, for example:
+
+```ruby
+lace.pull_ranges
+# => [2015-03-05 10:08:00 +0200...2015-03-06 10:08:00 +0200,
+#     2015-03-06 10:08:00 +0200...2015-03-07 10:08:00 +0200,
+#     2015-03-07 10:08:00 +0200...2015-03-08 10:08:00 +0200,
+#     2015-03-08 10:08:00 +0200...2015-03-09 10:08:00 +0200,
+#     2015-03-09 10:08:00 +0200...2015-03-09 11:07:00 +0200]
+
+# Now, you can do something like:
+
+lace.pull_ranges.map{|range| dataset.where(timestamp: range).count}
+# ...and have your daily stats with one line of code
+
+```
+
+## Got it, what else?
+
+TimeMath also play well when included into other classes or modules:
+
+```ruby
+class MyModel
+  include TimeMath
+
+  def next_day
+    day.advance # Here!
+  end
+end
+```
+
+## Alternatives
+
+There's pretty small and useful [AS::Duration](https://github.com/janko-m/as-duration)
+by Janko Marohnić, which is time durations, extracted from ActiveSupport,
+but without any ActiveSupport bloat.
+
+## Links
+
+* [API Docs](http://www.rubydoc.info/gems/time_math2)
+
+## Author
+
+[Victor Shepelev](http://zverok.github.io/)
+
+## License
+
+[MIT](https://github.com/zverok/time_math2/blob/master/LICENSE.txt).

data/lib/time_math/core_ext.rb

@@ -0,0 +1,52 @@
+module TimeMath
+  # This module is included into `Time` and `DateTime`. It is optional
+  # and only included by explicit `require "time_math/core_ext"`.
+  module CoreExt
+    # @!method floor_to(unit)
+    #   Shortcut to {Units::Base#floor}
+    # @!method ceil_to(unit)
+    #   Shortcut to {Units::Base#ceil}
+    # @!method round_to(unit)
+    #   Shortcut to {Units::Base#round}
+    # @!method next_to(unit)
+    #   Shortcut to {Units::Base#next}
+    # @!method prev_to(unit)
+    #   Shortcut to {Units::Base#prev}
+    [:floor, :ceil, :round, :next, :prev].each do |sym|
+      define_method("#{sym}_to") { |unit| TimeMath[unit].send(sym, self) }
+    end
+
+    # Shortcut to {Units::Base#round?}
+    def round_to?(unit)
+      TimeMath[unit].round?(self)
+    end
+
+    # Shortcut to {Units::Base#advance}
+    def advance_by(unit, amount = 1)
+      TimeMath[unit].advance(self, amount)
+    end
+
+    # Shortcut to {Units::Base#decrease}
+    def decrease_by(unit, amount = 1)
+      TimeMath[unit].decrease(self, amount)
+    end
+
+    # Shortcut to {Units::Base#range}
+    def range_to(unit, amount = 1)
+      TimeMath[unit].range(self, amount)
+    end
+
+    # Shortcut to {Units::Base#range_back}
+    def range_from(unit, amount = 1)
+      TimeMath[unit].range_back(self, amount)
+    end
+
+    # Shortcut to {Units::Base#sequence}. See its docs for possible options.
+    def sequence_to(unit, other, options = {})
+      TimeMath[unit].sequence(self, other, options)
+    end
+  end
+
+  Time.send :include, CoreExt
+  DateTime.send :include, CoreExt if ::Kernel.const_defined?(:DateTime)
+end

data/lib/time_math/measure.rb

@@ -0,0 +1,33 @@
+# encoding: utf-8
+module TimeMath
+  # @private
+  module Measure
+    PLURALS = {
+      year: :years,
+      month: :months,
+      week: :weeks,
+      day: :days,
+      hour: :hours,
+      min: :minutes,
+      sec: :seconds
+    }.freeze
+
+    def self.measure(from, to, options = {})
+      select_units(options).reverse.inject({}) do |res, unit|
+        span, from = Units.get(unit).measure_rem(from, to)
+        res.merge(PLURALS[unit] => span)
+      end
+    end
+
+    def self.select_units(options)
+      units = Units.names
+      units.delete(:week) if options[:weeks] == false
+
+      if (idx = units.index(options[:upto]))
+        units = units.first(idx + 1)
+      end
+
+      units
+    end
+  end
+end

data/lib/time_math/sequence.rb

@@ -0,0 +1,175 @@
+module TimeMath
+  # Sequence represents a sequential units of time between two points.
+  # It has several options and convenience methods for creating arrays of
+  # data.
+  #
+  # Basic usage example:
+  #
+  # ```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)>
+  # ```
+  #
+  # 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.
+  #
+  # You can expand from and to to nearest round unit by {#expand} method
+  # or `:expand` option:
+  #
+  # ```ruby
+  # 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.to_a
+  # ```
+  #
+  # 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.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
+  # # => [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]
+  # ```
+  #
+  # It is pretty convenient for filtering data from databases or APIs,
+  # TimeMath creates list of filtering ranges in a blink.
+  #
+  class Sequence
+    # Creates a sequence. Typically, it is easier to to it with {Units::Base#sequence},
+    # like this:
+    #
+    # ```ruby
+    # 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 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.
+    #
+    def initialize(unit, from, to, options = {})
+      @unit = Units.get(unit)
+      @from, @to = from, to
+      @options = options.dup
+
+      expand! if options[:expand]
+      @floor = options[:floor]
+    end
+
+    attr_reader :from, :to, :unit
+
+    def ==(other)
+      self.class == other.class && unit == other.unit &&
+        from == other.from && to == other.to
+    end
+
+    # If `:floor` option is set for sequence.
+    def floor?
+      @floor
+    end
+
+    # Expand sequence ends to nearest round unit.
+    #
+    # @return self
+    def expand!
+      @from = unit.floor(from)
+      @to = unit.ceil(to)
+
+      self
+    end
+
+    # Creates new sequence with ends rounded to nearest unit.
+    #
+    # @return [Sequence]
+    def expand
+      dup.tap(&:expand!)
+    end
+
+    # Sets sequence to floor all the intermediate values.
+    #
+    # @return self
+    def floor!
+      @floor = true
+    end
+
+    # Creates new sequence with setting to floor all the intermediate
+    # values.
+    #
+    # @return [Sequence]
+    def floor
+      dup.tap(&:floor!)
+    end
+
+    # Creates an array of time unit starts between from and to. They will
+    # have same granularity as from (e.g. if unit is day and from is
+    # 2016-05-01 13:30, each of return values will be next day at 13:30),
+    # unless sequence is not set to floor values.
+    #
+    # @return [Array<Time or DateTime>]
+    def to_a
+      seq = []
+
+      iter = from
+      while iter < to
+        seq << iter
+
+        iter = cond_floor(unit.advance(iter))
+      end
+
+      seq
+    end
+
+    # Creates an array of pairs (time unit start, time unit end) between
+    # from and to.
+    #
+    # @return [Array<Array>]
+    def pairs
+      seq = to_a
+      seq.zip(seq[1..-1] + [to])
+    end
+
+    # Creates an array of Ranges (time unit start...time unit end) between
+    # from and to.
+    #
+    # @return [Array<Range>]
+    def ranges
+      pairs.map { |b, e| (b...e) }
+    end
+
+    def inspect
+      "#<#{self.class}(#{from} - #{to})>"
+    end
+
+    private
+
+    def cond_floor(tm)
+      @floor ? unit.floor(tm) : tm
+    end
+  end
+end

data/lib/time_math/span.rb

@@ -0,0 +1,53 @@
+module TimeMath
+  # Represents time span (amount of units), like "4 years".
+  # Allows to advance or decrease Time or DateTime.
+  #
+  # Use it like this:
+  #
+  # ```ruby
+  # TimeMath.year.span(4).before(Time.now)
+  # ```
+  #
+  class Span
+    attr_reader :unit, :amount
+
+    # Creates Span instance.
+    # Typically, it is easire to use {Units::Base#span} than create
+    # spans directly.
+    #
+    # @param unit [Symbol] one of {Units.names}, unit of span;
+    # @param amount [Integer] amount of units in span.
+    def initialize(unit, amount)
+      @unit, @amount = unit, amount
+      @unit_impl = Units.get(unit)
+    end
+
+    # Decreases `tm` by `amount` of `unit`.
+    #
+    # @param tm [Time,DateTime] time value to decrease;
+    # @return [Time,DateTime] decreased time.
+    def before(tm = Time.now)
+      @unit_impl.decrease(tm, amount)
+    end
+
+    # Increases `tm` by `amount` of `unit`.
+    #
+    # @param tm [Time,DateTime] time value to increase;
+    # @return [Time,DateTime] increased time.
+    def after(tm = Time.now)
+      @unit_impl.advance(tm, amount)
+    end
+
+    alias ago before
+    alias from after
+
+    def ==(other)
+      self.class == other.class &&
+        unit == other.unit && amount == other.amount
+    end
+
+    def inspect
+      '#<%s(%s): %+i>' % [self.class, unit, amount]
+    end
+  end
+end