Class: TimeCalc

Inherits:
Object
  • Object
show all
Defined in:
lib/time_calc.rb,
lib/time_calc/op.rb,
lib/time_calc/dst.rb,
lib/time_calc/diff.rb,
lib/time_calc/types.rb,
lib/time_calc/units.rb,
lib/time_calc/value.rb,
lib/time_calc/version.rb,
lib/time_calc/sequence.rb

Overview

Module for time arithmetic.

Examples of usage:

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.

Defined Under Namespace

Modules: DST, Types, Units Classes: Diff, Op, Sequence, Value

Constant Summary collapse

MATH_OPERATIONS = 
%i[merge truncate floor ceil round + - iterate].freeze
OPERATIONS = 
MATH_OPERATIONS.+(%i[to step for]).freeze
VERSION = 
'0.0.4'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(date_or_time) ⇒ TimeCalc

Creates a "temporary" wrapper, which would be unwrapped after first operation:

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:

TimeCalc.(Time.now).round(:hour)
# => 2019-07-03 23:00:00 +0300

# There is another shortcut for those who disapprove on `.()`
TimeCalc[Time.now].+(1, :month)

See from if you need to perform several math operations on same value.

Parameters:

  • date_or_time (Time, Date, DateTime) 


130
131
132
 
# File 'lib/time_calc.rb', line 130

def initialize(date_or_time)
  @value = Value.new(date_or_time)
end

Instance Attribute Details

#value ⇒ Object (readonly) 



108
109
110
 
# File 'lib/time_calc.rb', line 108

def value
  @value
end

Class Method Details

.+(span, unit) ⇒ Op

Creates operation to perform #+(span, unit)

Returns:



3
 
# File 'lib/time_calc.rb', line 3

def TimeCalc.+(span, unit); end

.-(span, unit) ⇒ Op

Returns:



9
 
# File 'lib/time_calc.rb', line 9

def TimeCalc.-(span, unit); end

.ceil(unit) ⇒ Op

Returns:



15
 
# File 'lib/time_calc.rb', line 15

def TimeCalc.ceil(unit); end

.floor(unit) ⇒ Op

Returns:



12
 
# File 'lib/time_calc.rb', line 12

def TimeCalc.floor(unit); end

.from(date_or_time) ⇒ Value Also known as: wrap

Returns Value wrapper, useful for performing several operations at once:

TimeCalc.from(Time.parse('2019-06-14 13:40')).+(10, :days).floor(:week).unwrap
# => 2019-06-24 00:00:00 +0300

Parameters:

  • date_or_time (Time, Date, DateTime)

Returns:



86
87
88
 
# File 'lib/time_calc.rb', line 86

def from(date_or_time)
  Value.new(date_or_time)
end

.from_now ⇒ Value Also known as: wrap_now

Shortcut for TimeCalc.from(Time.now)

Returns:



92
93
94
 
# File 'lib/time_calc.rb', line 92

def from_now
  from(Time.now)
end

.from_today ⇒ Value Also known as: wrap_today

Shortcut for TimeCalc.from(Date.today)

Returns:



98
99
100
 
# File 'lib/time_calc.rb', line 98

def from_today
  from(Date.today)
end

.iterate(span, unit, &block) ⇒ Op

Returns:



6
 
# File 'lib/time_calc.rb', line 6

def TimeCalc.iterate(span, unit, &block); end

.now ⇒ TimeCalc

Shortcut for TimeCalc.(Time.now)

Returns:



67
68
69
 
# File 'lib/time_calc.rb', line 67

def now
  new(Time.now)
end

.round(unit) ⇒ Op

Returns:



18
 
# File 'lib/time_calc.rb', line 18

def TimeCalc.round(unit); end

.today ⇒ TimeCalc

Shortcut for TimeCalc.(Date.today)

Returns:



73
74
75
 
# File 'lib/time_calc.rb', line 73

def today
  new(Date.today)
end

Instance Method Details

#+(span, unit) ⇒ Date, ...

Add <span units> to wrapped value

Examples:

TimeCalc.(Time.parse('2019-07-03 23:28:54')).+(1, :day)
# => 2019-07-04 23:28:54 +0300

Parameters:

  • span (Integer)
  • unit (Symbol)

Returns:

  • (Date, Time, DateTime) —

    value of the same type that was initial wrapped value.




# File 'lib/time_calc.rb', line 184

#-(span, unit) ⇒ Date, ... #-(date_or_time) ⇒ Diff

Overloads:

  • #-(span, unit) ⇒ Date, ...

    Subtracts span units from wrapped value.

    Parameters:

    • span (Integer)
    • unit (Symbol)

    Returns:

    • (Date, Time, DateTime) —

      value of the same type that was initial wrapped value.

  • #-(date_or_time) ⇒ Diff

    Produces Diff, allowing to calculate structured difference between two points in time.

    Examples:

    t1 = Time.parse('2019-06-01 14:50')
t2 = Time.parse('2019-06-15 12:10')
(TimeCalc.(t2) - t1).days
# => 13

    Parameters:

    • date_or_time (Date, Time, DateTime)

    Returns:

Returns:




# File 'lib/time_calc.rb', line 224

#==(other) ⇒ true, false

Returns:

  • (true, false) 


140
141
142
 
# File 'lib/time_calc.rb', line 140

def ==(other)
  other.is_a?(self.class) && other.value == value
end

#ceil(unit) ⇒ Time, ...

Ceils (rounds up) date/time to nearest unit.

Examples:

TimeCalc.(Time.parse('2018-06-23 12:30')).ceil(:month)
# => 2018-07-01 00:00:00 +0300

Parameters:

  • unit (Symbol)

Returns:

  • (Time, Date, DateTime) —

    value of the same type that was initial wrapped value.




# File 'lib/time_calc.rb', line 164

#floor(unit) ⇒ Time, ...

Floors (rounds down) date/time to nearest unit.

Examples:

TimeCalc.(Time.parse('2018-06-23 12:30')).floor(:month)
# => 2018-06-01 00:00:00 +0300

Parameters:

  • unit (Symbol)

Returns:

  • (Time, Date, DateTime) —

    value of the same type that was initial wrapped value.




# File 'lib/time_calc.rb', line 154

#for(span, unit) ⇒ Sequence

Produces Sequence from this value to this + <span units>

Examples:

TimeCalc.(Time.parse('2019-06-01 14:50')).for(2, :weeks).step(1, :day).count
# => 15

Parameters:

  • span (Integer)
  • unit (Symbol)

Returns:




# File 'lib/time_calc.rb', line 261

#inspect ⇒ Object 



135
136
137
 
# File 'lib/time_calc.rb', line 135

def inspect
  '#<%s(%s)>' % [self.class, @value.unwrap]
end

#iterate(span, unit) {|Time/Date/DateTime| ... } ⇒ Date, ...

Like #+, but allows conditional skipping of some periods. Increases value by unit at least span times, on each iteration checking with block provided if this point matches desired period; if it is not, it is skipped without increasing iterations counter. Useful for "business date/time" algorithms.

Examples:

# add 10 working days.
TimeCalc.(Time.parse('2019-07-03 23:28:54')).iterate(10, :days) { |t| (1..5).cover?(t.wday) }
# => 2019-07-17 23:28:54 +0300

# add 12 working hours
TimeCalc.(Time.parse('2019-07-03 13:28:54')).iterate(12, :hours) { |t| (9...18).cover?(t.hour) }
# => 2019-07-04 16:28:54 +0300

# negative spans are working, too:
TimeCalc.(Time.parse('2019-07-03 13:28:54')).iterate(-12, :hours) { |t| (9...18).cover?(t.hour) }
# => 2019-07-02 10:28:54 +0300

# zero span could be used to robustly enforce value into acceptable range
# (increasing forward till block is true):
TimeCalc.(Time.parse('2019-07-03 23:28:54')).iterate(0, :hours) { |t| (9...18).cover?(t.hour) }
# => 2019-07-04 09:28:54 +0300

Parameters:

  • span (Integer) —

    Could be positive or negative

  • unit (Symbol)

Yields:

  • (Time/Date/DateTime) —

    Object of wrapped class

Yield Returns:

  • (true, false) —

    If this point in time is "suitable". If the falsey value is returned, iteration is skipped without increasing the counter.

Returns:

  • (Date, Time, DateTime) —

    value of the same type that was initial wrapped value.




# File 'lib/time_calc.rb', line 193

#merge(**attrs) ⇒ Time, ...

Replaces specified components of date/time, preserves the rest.

Examples:

TimeCalc.(Date.parse('2018-06-01')).merge(year: 1983)
# => #<Date: 1983-06-01>

Parameters:

  • attrs (Hash<Symbol => Integer>)

Returns:

  • (Time, Date, DateTime) —

    value of the same type that was initial wrapped value.




# File 'lib/time_calc.rb', line 144

#round(unit) ⇒ Time, ...

Rounds (up or down) date/time to nearest unit.

Examples:

TimeCalc.(Time.parse('2018-06-23 12:30')).round(:month)
# => 2018-07-01 00:00:00 +0300

Parameters:

  • unit (Symbol)

Returns:

  • (Time, Date, DateTime) —

    value of the same type that was initial wrapped value.




# File 'lib/time_calc.rb', line 174

#step(unit) ⇒ Sequence #step(span, unit) ⇒ Sequence

Produces endless Sequence from this value, with step specified.

Overloads:

  • #step(unit) ⇒ Sequence

    Shortcut for step(1, unit)

    Parameters:

    • unit (Symbol)
  • #step(span, unit) ⇒ Sequence

    Examples:

    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]

    Parameters:

    • span (Integer)
    • unit (Symbol)

Returns:




# File 'lib/time_calc.rb', line 247

#to(date_or_time) ⇒ Sequence

Produces Sequence from this value to date_or_time

Parameters:

  • date_or_time (Date, Time, DateTime)

Returns:




# File 'lib/time_calc.rb', line 241