time_calc 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: '079469c094dfa9462e10854c885d962aeb8f047c'
+  data.tar.gz: c7f5d1d7d6f665b490ec48bb2d85a4830a030761
+SHA512:
+  metadata.gz: ba7158a430d4968675210fe5e981d203178d59aca4c2aadfd0de26fa856fff23740aa4b6280b9ce67d6e507f5c78ca8a1ee519cd0d74ffb5a6678fecd66209fd
+  data.tar.gz: c874789108c36d802ea023a7ea6dbb0956d4f835a05ca2318232f0cbddee5b3f942ded7f37d1373eec191ad7ab6b09aaca5df1a354db204e83b7a6a22d345bd7

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 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,149 @@
+# TimeCalc -- next generation of Time arithmetic library
+
+[![Gem Version](https://badge.fury.io/rb/time_calc.svg)](http://badge.fury.io/rb/time_calc)
+[![Build Status](https://travis-ci.org/zverok/time_calc.svg?branch=master)](https://travis-ci.org/zverok/time_calc)
+[![Documentation](http://b.repl.ca/v1/yard-docs-blue.png)](http://rubydoc.info/gems/time_calc/frames)
+
+**TimeCalc** tries to provide a way to do **simple time arithmetic** in a modern, readable, idiomatic, no-"magic" Ruby.
+
+_**NB:** TimeCalc is a continuation of [TimeMath](https://github.com/zverok/time_math2) project. As I decided to change API significantly (completely, in fact) and drop a lot of "nice to have but nobody uses" features, it is a new project rather than "absolutely incompatible new version". See [API design](#api-design) section to understand how and why TimeCalc is different._
+
+## Features
+
+* Small, clean, pure-Ruby, idiomatic, no monkey-patching, no dependencies (except `backports`);
+* Arithmetic akin to what Ruby numbers provide: `+`/`-`, `floor`/`ceil`/`round`, enumerable sequences (`step`/`to`);
+* Works with `Time`, `Date` and `DateTime` and allows to mix them freely (e.g. create sequences from `Date` to `Time`, calculate their diffs);
+* Tries its best to preserve timezone/offset information:
+  * **on Ruby 2.6+**, for `Time` with real timezones, preserves them;
+  * on Ruby < 2.6, preserves at least `utc_offset` of `Time`;
+  * for `DateTime` preserves zone name.
+
+## Synopsis
+
+### Arithmetic with units
+
+```ruby
+require 'time_calc'
+
+TC = TimeCalc
+
+t = Time.parse('2019-03-14 08:06:15')
+
+TC.(t).+(3, :hours)
+# => 2019-03-14 11:06:15 +0200
+TC.(t).round(:week)
+# => 2019-03-11 00:00:00 +0200
+
+# TimeCalc.call(Time.now) shortcut:
+TC.now.floor(:day)
+# => beginning of the today
+```
+
+Operations supported:
+
+* `+`, `-`
+* `ceil`, `round`, `floor`
+
+Units supported:
+
+* `:sec` (also `:second`, `:seconds`);
+* `:min` (`:minute`, `:minutes`);
+* `:hour`/`:hours`;
+* `:day`/`:days`;
+* `:week`/`:weeks`;
+* `:month`/`:months`;
+* `:year`/`:years`.
+
+Timezone preservation on Ruby 2.6:
+
+```ruby
+require 'tzinfo'
+t = Time.new(2019, 9, 1, 14, 30, 12, TZInfo::Timezone.get('Europe/Kiev'))
+# => 2019-09-01 14:30:12 +0300
+#                        ^^^^^
+TimeCalc.(t).+(3, :months) # jump over DST: we have +3 in summer and +2 in winter
+# => 2019-12-01 14:30:12 +0200
+#                        ^^^^^
+```
+<small>(Random fun fact: it is Kyiv, not Kiev!)</small>
+
+### Difference of two values
+
+```ruby
+diff = TC.(t) - Time.parse('2019-02-30 16:30')
+# => #<TimeCalc::Diff(2019-03-14 08:06:15 +0200 − 2019-03-02 16:30:00 +0200)>
+diff.days # or any other supported unit
+# => 11
+diff.factorize
+# => {:year=>0, :month=>0, :week=>1, :day=>4, :hour=>15, :min=>36, :sec=>15}
+```
+
+There are several options to [Diff#factorize](https://www.rubydoc.info/gems/time_calc/TimeCalc/Diff#factorize-instance_method) to obtain the most useful result.
+
+### Chains of operations
+
+```ruby
+TC.wrap(t).+(1, :hour).round(:min).unwrap
+# => 2019-03-14 09:06:00 +0200
+
+# proc constructor synopsys:
+times = ['2019-06-01 14:30', '2019-06-05 17:10', '2019-07-02 13:40'].map { |t| Time.parse(t) }
+times.map(&TC.+(1, :hour).round(:min))
+# => [2019-06-01 15:30:00 +0300, 2019-06-05 18:10:00 +0300, 2019-07-02 14:40:00 +0300]
+```
+
+### Enumerable time sequences
+
+```ruby
+TC.(t).step(2, :weeks)
+# => #<TimeCalc::Sequence (2019-03-14 08:06:15 +0200 - ...):step(2 weeks)>
+TC.(t).step(2, :weeks).first(3)
+# => [2019-03-14 08:06:15 +0200, 2019-03-28 08:06:15 +0200, 2019-04-11 09:06:15 +0300]
+TC.(t).to(Time.parse('2019-04-30 16:30')).step(3, :weeks).to_a
+# => [2019-03-14 08:06:15 +0200, 2019-04-04 09:06:15 +0300, 2019-04-25 09:06:15 +0300]
+TC.(t).for(3, :months).step(4, :weeks).to_a
+# => [2019-03-14 08:06:15 +0200, 2019-04-11 09:06:15 +0300, 2019-05-09 09:06:15 +0300, 2019-06-06 09:06:15 +0300]
+```
+
+## API design
+
+The idea of this library (as well as the idea of the previous one) grew of the simple question "how do you say `<some time> + 1 hour` in good Ruby?" This question also leads (me) to notifying that other arithmetical operations (like rounding, or `<value> up to <value> with step <value>`) seem to be applicable to `Time` or `Date` values as well.
+
+Prominent ActiveSupport's answer of extending simple numbers to respond to `1.year` never felt totally right to me. I am not completely against-any-monkey-patches kind of guy, it just doesn't sit right, to say "number has a method to produce duration". One of the attempts to find an alternative has led me to the creation of [time_math2](https://github.com/zverok/time_math2), which gained some (modest) popularity by presenting things this way: `TimeMath.year.advance(time, 1)`.
+
+TBH, using the library myself only eventually, I have never been too happy with it: it never felt really natural, so I constantly forgot "what should I do to calculate '2 days ago'". This simplest use case (some time from now) in `TimeMath` looked too far from "how you pronounce it":
+
+```ruby
+# Natural language: 2 days ago
+# "Formalized": now - 2 days
+
+# ActiveSupport:
+Time.now + 2.days
+# also there is 2.days.ago, but I am not a big fan of "1000 synonyms just for naturality"
+
+# TimeMath:
+TimMath.day.decrease(Time.now, 2) # Ughhh what? "Day decrease now 2"?
+```
+
+The thought process that led to the new library is:
+
+* `(2, days)` is just a _tuple_ of two unrelated data elements
+* `days` is "internal name that makes sense inside the code", which we represent by `Symbol` in Ruby
+* Math operators can be called just like regular methods: `.+(something)`, which may look unusual at first, but can be super-handy even with simple numbers, in method chaining -- I am grateful to my Verbit's colleague Roman Yarovoy to pointing at that fact (or rather its usefulness);
+* To chain some calculations with Ruby core type without extending this type, we can just "wrap" it into a monad-like object, do the calculations, and unwrap at the end (TimeMath itself, and my Hash-processing gem [hm](https://github.com/zverok/hm) have used this approach).
+
+So, here we go:
+```ruby
+TimeCalc.(Time.now).-(2, :days)
+# Small shortcut, as `Time.now` is the frequent start value for such calculations:
+TimeCalc.now.-(2, :days)
+```
+
+The rest of the design (see examples above) just followed naturally. There could be different opinions on the approach, but for myself the resulting API looks straightforward, hard to forget and very regular (in fact, all the hard time calculations, including support for different types, zones, DST and stuff, are done in two core methods, and the rest was easy to define in terms of those methods, which is a sign of consistency).
+
+¯\\\_(ツ)_/¯
+
+## Author & license
+
+* [Victor Shepelev](https://zverok.github.io)
+* [MIT](https://github.com/zverok/time_calc/blob/master/LICENSE.txt).

data/lib/time_calc.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'time'
+
+require_relative 'time_calc/units'
+require_relative 'time_calc/types'
+require_relative 'time_calc/dst'
+require_relative 'time_calc/value'
+
+# Module for time arithmetic.
+#
+# Examples of usage:
+#
+# ```ruby
+# TimeCalc.(Time.now).+(1, :day)
+# # => 2019-07-04 23:28:54 +0300
+# TimeCalc.(Time.now).round(:hour)
+# # => 2019-07-03 23:00:00 +0300
+#
+# # Operations with Time.now and Date.today also have their shortcuts:
+# TimeCalc.now.-(3, :days)
+# # => 2019-06-30 23:28:54 +0300
+# TimeCalc.today.ceil(:month)
+# # => #<Date: 2019-08-01 ((2458697j,0s,0n),+0s,2299161j)>
+#
+# # If you need to perform several operations TimeCalc.from wraps your value:
+# TimeCalc.from(Time.parse('2019-06-14 13:40')).+(10, :days).floor(:week).unwrap
+# # => 2019-06-24 00:00:00 +0300
+#
+# # TimeCalc#- also can be used to calculate difference between time values
+# diff = TimeCalc.(Time.parse('2019-07-03 23:32')) - Time.parse('2019-06-14 13:40')
+# # => #<TimeCalc::Diff(2019-07-03 23:32:00 +0300 − 2019-06-14 13:40:00 +0300)>
+# diff.days # => 19
+# diff.hours # => 465
+# diff.factorize
+# # => {:year=>0, :month=>0, :week=>2, :day=>5, :hour=>9, :min=>52, :sec=>0}
+# diff.factorize(max: :day)
+# # => {:day=>19, :hour=>9, :min=>52, :sec=>0}
+#
+# # Enumerable sequences of time values
+# sequence = TimeCalc.(Time.parse('2019-06-14 13:40'))
+#                    .to(Time.parse('2019-07-03 23:32'))
+#                    .step(5, :hours)
+# # => #<TimeCalc::Sequence (2019-06-14 13:40:00 +0300 - 2019-07-03 23:32:00 +0300):step(5 hours)>
+# sequence.to_a
+# # => [2019-06-14 13:40:00 +0300, 2019-06-14 18:40:00 +0300, 2019-06-14 23:40:00 +0300, ...
+# sequence.first(2)
+# # => [2019-06-14 13:40:00 +0300, 2019-06-14 18:40:00 +0300]
+#
+# # Construct operations to apply as a proc:
+# times = ['2019-06-01 14:30', '2019-06-05 17:10', '2019-07-02 13:40'].map { |t| Time.parse(t) }
+# # => [2019-06-01 14:30:00 +0300, 2019-06-05 17:10:00 +0300, 2019-07-02 13:40:00 +0300]
+# times.map(&TimeCalc.+(1, :week).round(:day))
+# # => [2019-06-09 00:00:00 +0300, 2019-06-13 00:00:00 +0300, 2019-07-10 00:00:00 +0300]
+# ```
+#
+# See method docs below for details and supported arguments.
+#
+class TimeCalc
+  class << self
+    alias call new
+
+    # Shortcut for `TimeCalc.(Time.now)`
+    # @return [TimeCalc]
+    def now
+      new(Time.now)
+    end
+
+    # Shortcut for `TimeCalc.(Date.today)`
+    # @return [TimeCalc]
+    def today
+      new(Date.today)
+    end
+
+    # Returns {Value} wrapper, useful for performing several operations at once:
+    #
+    # ```ruby
+    # TimeCalc.from(Time.parse('2019-06-14 13:40')).+(10, :days).floor(:week).unwrap
+    # # => 2019-06-24 00:00:00 +0300
+    # ```
+    #
+    # @param date_or_time [Time, Date, DateTime]
+    # @return [Value]
+    def from(date_or_time)
+      Value.new(date_or_time)
+    end
+
+    # Shortcut for `TimeCalc.from(Time.now)`
+    # @return [Value]
+    def from_now
+      from(Time.now)
+    end
+
+    # Shortcut for `TimeCalc.from(Date.today)`
+    # @return [Value]
+    def from_today
+      from(Date.today)
+    end
+
+    alias wrap from
+    alias wrap_now from_now
+    alias wrap_today from_today
+  end
+
+  # @private
+  attr_reader :value
+
+  # Creates a "temporary" wrapper, which would be unwrapped after first operation:
+  #
+  # ```ruby
+  # TimeCalc.new(Time.now).round(:hour)
+  # # => 2019-07-03 23:00:00 +0300
+  # ```
+  #
+  # The constructor also aliased as `.call` which allows for nicer (for some eyes) code:
+  #
+  # ```ruby
+  # TimeCalc.(Time.now).round(:hour)
+  # # => 2019-07-03 23:00:00 +0300
+  # ```
+  #
+  # See {.from} if you need to perform several math operations on same value.
+  #
+  # @param date_or_time [Time, Date, DateTime]
+  def initialize(date_or_time)
+    @value = Value.new(date_or_time)
+  end
+
+  # @private
+  def inspect
+    '#<%s(%s)>' % [self.class, @value.unwrap]
+  end
+
+  # @return [true,false]
+  def ==(other)
+    other.is_a?(self.class) && other.value == value
+  end
+
+  # @!method merge(**attrs)
+  #   Replaces specified components of date/time, preserves the rest.
+  #
+  #   @example
+  #      TimeCalc.(Date.parse('2018-06-01')).merge(year: 1983)
+  #      # => #<Date: 1983-06-01>
+  #
+  #   @param attrs [Hash<Symbol => Integer>]
+  #   @return [Time, Date, DateTime] value of the same type that was initial wrapped value.
+
+  # @!method floor(unit)
+  #   Floors (rounds down) date/time to nearest `unit`.
+  #
+  #   @example
+  #     TimeCalc.(Time.parse('2018-06-23 12:30')).floor(:month)
+  #     # => 2018-06-01 00:00:00 +0300
+  #
+  #   @param unit [Symbol]
+  #   @return [Time, Date, DateTime] value of the same type that was initial wrapped value.
+
+  # @!method ceil(unit)
+  #   Ceils (rounds up) date/time to nearest `unit`.
+  #
+  #   @example
+  #     TimeCalc.(Time.parse('2018-06-23 12:30')).ceil(:month)
+  #     # => 2018-07-01 00:00:00 +0300
+  #
+  #   @param unit [Symbol]
+  #   @return [Time, Date, DateTime] value of the same type that was initial wrapped value.
+
+  # @!method round(unit)
+  #   Rounds (up or down) date/time to nearest `unit`.
+  #
+  #   @example
+  #     TimeCalc.(Time.parse('2018-06-23 12:30')).round(:month)
+  #     # => 2018-07-01 00:00:00 +0300
+  #
+  #   @param unit [Symbol]
+  #   @return [Time, Date, DateTime] value of the same type that was initial wrapped value.
+
+  # @!method +(span, unit)
+  #   Add `<span units>` to wrapped value
+  #   @example
+  #      TimeCalc.(Time.parse('2019-07-03 23:28:54')).+(1, :day)
+  #      # => 2019-07-04 23:28:54 +0300
+  #   @param span [Integer]
+  #   @param unit [Symbol]
+  #   @return [Date, Time, DateTime] value of the same type that was initial wrapped value.
+
+  # @!method -(span_or_other, unit=nil)
+  #   @overload -(span, unit)
+  #     Subtracts `span units` from wrapped value.
+  #     @param span [Integer]
+  #     @param unit [Symbol]
+  #     @return [Date, Time, DateTime] value of the same type that was initial wrapped value.
+  #   @overload -(date_or_time)
+  #     Produces {Diff}, allowing to calculate structured difference between two points in time.
+  #     @example
+  #       t1 = Time.parse('2019-06-01 14:50')
+  #       t2 = Time.parse('2019-06-15 12:10')
+  #       (TimeCalc.(t2) - t1).days
+  #       # => 13
+  #     @param date_or_time [Date, Time, DateTime]
+  #     @return [Diff]
+  #   @return [Time or Diff]
+
+  # @!method to(date_or_time)
+  #   Produces {Sequence} from this value to `date_or_time`
+  #
+  #   @param date_or_time [Date, Time, DateTime]
+  #   @return [Sequence]
+
+  # @!method step(span, unit = nil)
+  #   Produces endless {Sequence} from this value, with step specified.
+  #
+  #   @overload step(unit)
+  #     Shortcut for `step(1, unit)`
+  #     @param unit [Symbol]
+  #   @overload step(span, unit)
+  #     @example
+  #       TimeCalc.(Time.parse('2019-06-01 14:50')).step(1, :day).take(3)
+  #       # => [2019-06-01 14:50:00 +0300, 2019-06-02 14:50:00 +0300, 2019-06-03 14:50:00 +0300]
+  #     @param span [Integer]
+  #     @param unit [Symbol]
+  #   @return [Sequence]
+
+  # @!method for(span, unit)
+  #   Produces {Sequence} from this value to `this + <span units>`
+  #
+  #   @example
+  #     TimeCalc.(Time.parse('2019-06-01 14:50')).for(2, :weeks).step(1, :day).count
+  #     # => 15
+  #   @param span [Integer]
+  #   @param unit [Symbol]
+  #   @return [Sequence]
+
+  # @private
+  MATH_OPERATIONS = %i[merge truncate floor ceil round + -].freeze
+  # @private
+  OPERATIONS = MATH_OPERATIONS.+(%i[to step for]).freeze
+
+  OPERATIONS.each do |name|
+    define_method(name) { |*args|
+      @value.public_send(name, *args).then { |res| res.is_a?(Value) ? res.unwrap : res }
+    }
+  end
+
+  class << self
+    MATH_OPERATIONS.each do |name|
+      define_method(name) { |*args| Op.new([[name, *args]]) }
+    end
+
+    # @!parse
+    #   # Creates operation to perform {#+}`(span, unit)`
+    #   # @return [Op]
+    #   def TimeCalc.+(span, unit); end
+    #   # Creates operation to perform {#-}`(span, unit)`
+    #   # @return [Op]
+    #   def TimeCalc.-(span, unit); end
+    #   # Creates operation to perform {#floor}`(unit)`
+    #   # @return [Op]
+    #   def TimeCalc.floor(unit); end
+    #   # Creates operation to perform {#ceil}`(unit)`
+    #   # @return [Op]
+    #   def TimeCalc.ceil(unit); end
+    #   # Creates operation to perform {#round}`(unit)`
+    #   # @return [Op]
+    #   def TimeCalc.round(unit); end
+  end
+end
+
+require_relative 'time_calc/op'
+require_relative 'time_calc/sequence'
+require_relative 'time_calc/diff'