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) 


42
43
44
 
# File 'lib/time_calc/value.rb', line 42

def initialize(time_or_date)
  @internal = time_or_date
end

Instance Attribute Details

#internal ⇒ Object (readonly) 



37
38
39
 
# File 'lib/time_calc/value.rb', line 37

def internal
  @internal
end

Class Method Details

.wrap(value) ⇒ Object 



23
24
25
26
27
28
29
30
31
32
33
34
 
# File 'lib/time_calc/value.rb', line 23

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:



138
139
140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/time_calc/value.rb', line 138

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:



162
163
164
 
# File 'lib/time_calc/value.rb', line 162

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) 


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

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:



115
116
117
 
# File 'lib/time_calc/value.rb', line 115

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

#convert(klass) ⇒ Object 



198
199
200
201
202
 
# File 'lib/time_calc/value.rb', line 198

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

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

#dst? ⇒ Boolean

Returns:

  • (Boolean) 


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

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:



193
194
195
 
# File 'lib/time_calc/value.rb', line 193

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

#inspect ⇒ Object 



52
53
54
 
# File 'lib/time_calc/value.rb', line 52

def inspect
  '#<%s(%s)>' % [self.class, internal]
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:



81
82
83
 
# File 'lib/time_calc/value.rb', line 81

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



127
128
129
130
131
 
# File 'lib/time_calc/value.rb', line 127

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:



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

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:



170
171
172
 
# File 'lib/time_calc/value.rb', line 170

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



94
95
96
97
98
99
100
101
102
103
 
# File 'lib/time_calc/value.rb', line 94

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(&method(:merge))
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



47
48
49
 
# File 'lib/time_calc/value.rb', line 47

def unwrap
  @internal
end