Class: TimeCalc::Value

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/time_calc/value.rb

Overview

Wrapper (one can say “monad”) around date/time value, allowing to perform several TimeCalc operations in a chain.

Examples:

TimeCalc.wrap(Time.parse('2019-06-01 14:50')).+(1, :year).-(1, :month).round(:week).unwrap
# => 2020-05-04 00:00:00 +0300

Constant Summary collapse

TIMEY = 
proc { |t| t.respond_to?(:to_time) }

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(time_or_date) ⇒ Value

Note:

Prefer TimeCalc.wrap to create a Value.

Returns a new instance of Value.

Parameters:

  • time_or_date (Time, Date, DateTime) 


63
64
65
 
# File 'lib/time_calc/value.rb', line 63

def initialize(time_or_date)
  @internal = time_or_date
end

Instance Attribute Details

#internal ⇒ Object (readonly) 



58
59
60
 
# File 'lib/time_calc/value.rb', line 58

def internal
  @internal
end

Class Method Details

.wrap(value) ⇒ Object 



44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/time_calc/value.rb', line 44

def self.wrap(value)
  case value
  when Time, Date, DateTime
    new(value)
  when Value
    value
  when TIMEY
    wrap(value.to_time)
  else
    fail ArgumentError, "Unsupported value: #{value}"
  end
end

Instance Method Details

#+(span, unit) ⇒ Value

Add ‘<span units>` to wrapped value.

Parameters:

  • span (Integer)
  • unit (Symbol)

Returns:



159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/time_calc/value.rb', line 159

def +(span, unit)
  unit = Units.(unit)
  case unit
  when :sec, :min, :hour, :day
    plus_seconds(span, unit)
  when :week
    self.+(span * 7, :day)
  when :month
    plus_months(span)
  when :year
    merge(year: year + span)
  end
end

#-(span, unit) ⇒ Value #-(date_or_time) ⇒ Diff

Subtracts ‘span units` from wrapped value.

Overloads:

  • #-(span, unit) ⇒ Value

    Subtracts ‘span units` from wrapped value.

    Parameters:

    • span (Integer)
    • unit (Symbol)

    Returns:

  • #-(date_or_time) ⇒ Diff

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

    Parameters:

    • date_or_time (Date, Time, DateTime)

    Returns:



183
184
185
 
# File 'lib/time_calc/value.rb', line 183

def -(span_or_other, unit = nil)
  unit.nil? ? Diff.new(self, span_or_other) : self.+(-span_or_other, unit)
end

#<=>(other) ⇒ 1, ...

Returns:

  • (1, 0, -1) 


78
79
80
81
82
 
# File 'lib/time_calc/value.rb', line 78

def <=>(other)
  return unless other.is_a?(self.class)

  Types.compare(internal, other.internal)
end

#ceil(unit) ⇒ Value

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

Examples:

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

Parameters:

  • unit (Symbol)

Returns:



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

def ceil(unit)
  floor(unit).then { |res| res == self ? res : res.+(1, unit) }
end

#convert(klass) ⇒ Object 



241
242
243
244
245
 
# File 'lib/time_calc/value.rb', line 241

def convert(klass)
  return dup if internal.class == klass

  Value.new(Types.convert(internal, klass))
end

#dst? ⇒ Boolean

Returns:

  • (Boolean) 


88
89
90
91
92
 
# File 'lib/time_calc/value.rb', line 88

def dst?
  return unless internal.respond_to?(:dst?)

  internal.dst?
end

#for(span, unit) ⇒ Sequence

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

Parameters:

  • span (Integer)
  • unit (Symbol)

Returns:



236
237
238
 
# File 'lib/time_calc/value.rb', line 236

def for(span, unit)
  to(self.+(span, unit))
end

#inspect ⇒ Object 



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

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

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

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.

See TimeCalc#iterate for examples.

Parameters:

  • span (Integer)
  • 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:



200
201
202
203
204
205
206
207
 
# File 'lib/time_calc/value.rb', line 200

def iterate(span, unit)
  block_given? or fail ArgumentError, 'No block given'
  Integer === span or fail ArgumentError, 'Only integer spans are supported' # rubocop:disable Style/CaseEquality

  Enumerator.produce(self) { |v| v.+((span <=> 0).nonzero? || 1, unit) }
            .lazy.select { |v| yield(v.internal) }
            .drop(span.abs).first
end

#merge(**attrs) ⇒ Value

Produces new value with some components of underlying time/date replaced.

Examples:

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

Parameters:

  • attrs (Hash<Symbol => Integer>)

Returns:



102
103
104
 
# File 'lib/time_calc/value.rb', line 102

def merge(**attrs)
  Value.new(Types.public_send("merge_#{internal.class.name.downcase}", internal, **attrs))
end

#round(unit) ⇒ Object

Rounds up or down underlying date/time to nearest ‘unit`.

Examples:

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

Parameters:

  • unit (Symbol)

Returns:

  • Value



148
149
150
151
152
 
# File 'lib/time_calc/value.rb', line 148

def round(unit)
  f, c = floor(unit), ceil(unit)

  (internal - f.internal).abs < (internal - c.internal).abs ? f : c
end

#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

    Parameters:

    • span (Integer)
    • unit (Symbol)

Returns:



226
227
228
229
 
# File 'lib/time_calc/value.rb', line 226

def step(span, unit = nil)
  span, unit = 1, span if unit.nil?
  Sequence.new(from: self).step(span, unit)
end

#to(date_or_time) ⇒ Sequence

Produces Sequence from this value to ‘date_or_time`

Parameters:

  • date_or_time (Date, Time, DateTime)

Returns:



213
214
215
 
# File 'lib/time_calc/value.rb', line 213

def to(date_or_time)
  Sequence.new(from: self).to(date_or_time)
end

#truncate(unit) ⇒ Object Also known as: floor

Truncates all time components lower than ‘unit`. In other words, “floors” (rounds down) underlying date/time to nearest `unit`.

Examples:

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

Parameters:

  • unit (Symbol)

Returns:

  • Value



115
116
117
118
119
120
121
122
123
124
 
# File 'lib/time_calc/value.rb', line 115

def truncate(unit)
  unit = Units.(unit)
  return floor_week if unit == :week

  Units::STRUCTURAL
    .drop_while { |u| u != unit }
    .drop(1)
    .then { |keys| Units::DEFAULTS.slice(*keys) }
    .then { |attrs| merge(**attrs) } # can't simplify to &method(:merge) due to 2.7 keyword param problem
end

#unwrap ⇒ Time, ...

Returns The value of the original type that was wrapped and processed.

Returns:

  • (Time, Date, DateTime) —

    The value of the original type that was wrapped and processed



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

def unwrap
  @internal
end