Class: ISO8601::TimeInterval

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/iso8601/time_interval.rb

Overview

A Time Interval representation. See en.wikipedia.org/wiki/ISO_8601#Time_intervals

Examples:

ti = ISO8601::TimeInterval.parse('P1MT2H/2014-05-28T19:53Z')
ti.size # => 2635200.0
ti2 = ISO8601::TimeInterval.parse('2014-05-28T19:53Z/2014-05-28T20:53Z')
ti2.to_f # => 3600.0
start_time = ISO8601::DateTime.new('2014-05-28T19:53Z')
end_time = ISO8601::DateTime.new('2014-05-30T19:53Z')
ti = ISO8601::TimeInterval.from_datetimes(start_time, end_time)
ti.size # => 172800.0 (Seconds)
duration = ISO8601::Duration.new('P1MT2H')
end_time = ISO8601::DateTime.new('2014-05-30T19:53Z')
ti = ISO8601::TimeInterval.from_duration(duration, end_time)
ti.size # => 2635200.0 (Seconds)
start_time = ISO8601::DateTime.new('2014-05-30T19:53Z')
duration = ISO8601::Duration.new('P1MT2H', base)
ti = ISO8601::TimeInterval.from_duration(start_time, duration)
ti.size # => 2635200.0 (Seconds)

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#new(pattern) ⇒ ISO8601::TimeInterval #new([start_time, duration]) ⇒ ISO8601::TimeInterval #new([duration, end_time]) ⇒ ISO8601::TimeInterval

Dispatches the constructor based on the type of the input.

Overloads:



93
94
95
96
97
98
99
100
101
102
 
# File 'lib/iso8601/time_interval.rb', line 93

def initialize(input)
  case input
  when String
    parse(input)
  when Array
    from_atoms(input)
  else
    raise(ISO8601::Errors::TypeError, 'The pattern must be a String or a Hash')
  end
end

Instance Attribute Details

#first ⇒ ISO8601::DateTime (readonly) Also known as: start_time

The start time (first) of the interval.

Returns:



115
116
117
 
# File 'lib/iso8601/time_interval.rb', line 115

def first
  @first
end

#last ⇒ ISO8601::DateTime (readonly) Also known as: end_time

The end time (last) of the interval.

Returns:



122
123
124
 
# File 'lib/iso8601/time_interval.rb', line 122

def last
  @last
end

#size ⇒ Float (readonly) Also known as: to_f, length

The size of the interval. If any bound is a Duration, the size of the interval is the number of seconds of the interval.

Returns:

  • (Float) —

    Size of the interval in seconds



141
142
143
 
# File 'lib/iso8601/time_interval.rb', line 141

def size
  @size
end

Class Method Details

.from_datetimes(start_time, end_time) ⇒ ISO8601::TimeInterval

Initializes a time interval based on two time points.

Parameters:

Returns:

Raises:



47
48
49
50
 
# File 'lib/iso8601/time_interval.rb', line 47

def self.from_datetimes(*atoms)
  guard_from_datetimes(atoms, 'Start and end times must instances of ISO8601::DateTime')
  new(atoms)
end

.from_duration(start_time, duration) ⇒ ISO8601::TimeInterval .from_duration(duration, end_time) ⇒ ISO8601::TimeInterval

Initializes a TimeInterval based on a ‘ISO8601::Duration` and a `ISO8601::DateTime`. The order of the params define the strategy to compute the interval.

Overloads:

Returns:

Raises:



72
73
74
75
 
# File 'lib/iso8601/time_interval.rb', line 72

def self.from_duration(*atoms)
  guard_from_duration(atoms, 'Expected one date time and one duration')
  new(atoms)
end

.guard_from_datetimes(atoms, message) ⇒ Object 



284
285
286
 
# File 'lib/iso8601/time_interval.rb', line 284

def self.guard_from_datetimes(atoms, message)
  atoms.all? { |x| valid_date_time?(x, message) }
end

.guard_from_duration(atoms, message) ⇒ Object

Raises:



288
289
290
291
292
 
# File 'lib/iso8601/time_interval.rb', line 288

def self.guard_from_duration(atoms, message)
  raise(ISO8601::Errors::TypeError, message) \
    unless atoms.any? { |x| x.is_a?(ISO8601::Duration) } &&
           atoms.any? { |x| x.is_a?(ISO8601::DateTime) }
end

.parse(pattern) ⇒ Object

Alias of ‘initialize` to have a closer interface to the core `Time`, `Date` and `DateTime` interfaces.



107
108
109
 
# File 'lib/iso8601/time_interval.rb', line 107

def self.parse(pattern)
  new(pattern)
end

.valid_date_time?(time, message = "Expected a ISO8601::DateTime") ⇒ Boolean

Returns:

  • (Boolean)

Raises:



278
279
280
281
282
 
# File 'lib/iso8601/time_interval.rb', line 278

def self.valid_date_time?(time, message = "Expected a ISO8601::DateTime")
  return true if time.is_a?(ISO8601::DateTime)

  raise(ISO8601::Errors::TypeError, message)
end

Instance Method Details

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

Parameters:

Returns:

  • (-1, 0, 1, nil) 


256
257
258
259
260
 
# File 'lib/iso8601/time_interval.rb', line 256

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

  to_f <=> other.to_f
end

#disjoint?(other) ⇒ Boolean

Check if two intervarls have no element in common. This method is the opposite of ‘#intersect?`.

Parameters:

Returns:

  • (Boolean)

Raises:



248
249
250
 
# File 'lib/iso8601/time_interval.rb', line 248

def disjoint?(other)
  !intersect?(other)
end

#empty? ⇒ Boolean

Checks if the interval is empty.

Returns:

  • (Boolean) 


149
150
151
 
# File 'lib/iso8601/time_interval.rb', line 149

def empty?
  first == last
end

#eql?(other) ⇒ Boolean

Equality by hash.

Parameters:

Returns:

  • (Boolean) 


268
269
270
 
# File 'lib/iso8601/time_interval.rb', line 268

def eql?(other)
  (hash == other.hash)
end

#hash ⇒ Fixnum

Returns:

  • (Fixnum) 


274
275
276
 
# File 'lib/iso8601/time_interval.rb', line 274

def hash
  @atoms.hash
end

#include?(other) ⇒ Boolean Also known as: member?

Check if a given time is inside the current TimeInterval.

Parameters:

  • other (#to_time) —

    DateTime to check if it’s inside the current interval.

Returns:

  • (Boolean)

Raises:



163
164
165
166
167
168
169
 
# File 'lib/iso8601/time_interval.rb', line 163

def include?(other)
  raise(ISO8601::Errors::TypeError, "The parameter must respond_to #to_time") \
    unless other.respond_to?(:to_time)

  (first.to_time <= other.to_time &&
   last.to_time >= other.to_time)
end

#intersect?(other) ⇒ Boolean

Check if two intervarls intersect.

Parameters:

Returns:

  • (Boolean)

Raises:



213
214
215
216
217
218
 
# File 'lib/iso8601/time_interval.rb', line 213

def intersect?(other)
  raise(ISO8601::Errors::TypeError, "The parameter must be an instance of #{self.class}") \
    unless other.is_a?(self.class)

  include?(other.first) || include?(other.last)
end

#intersection(other) ⇒ Boolean

Return the intersection between two intervals.

Parameters:

Returns:

  • (Boolean)

Raises:



228
229
230
231
232
233
234
235
236
237
 
# File 'lib/iso8601/time_interval.rb', line 228

def intersection(other)
  raise(ISO8601::Errors::IntervalError, "The intervals are disjoint") \
    if disjoint?(other) && other.disjoint?(self)

  return self if subset?(other)
  return other if other.subset?(self)

  a, b = sort_pair(self, other)
  self.class.from_datetimes(b.first, a.last)
end

#pattern ⇒ String Also known as: to_s

The pattern for the interval.

Returns:

  • (String) —

    The pattern of this interval



129
130
131
132
133
 
# File 'lib/iso8601/time_interval.rb', line 129

def pattern
  return @pattern if @pattern

  "#{@atoms.first}/#{@atoms.last}"
end

#subset?(other) ⇒ Boolean

Returns true if the interval is a subset of the given interval.

Parameters:

Returns:

  • (Boolean)

Raises:



181
182
183
184
185
186
 
# File 'lib/iso8601/time_interval.rb', line 181

def subset?(other)
  raise(ISO8601::Errors::TypeError, "The parameter must be an instance of #{self.class}") \
    unless other.is_a?(self.class)

  other.include?(first) && other.include?(last)
end

#superset?(other) ⇒ Boolean

Returns true if the interval is a superset of the given interval.

Parameters:

Returns:

  • (Boolean)

Raises:



197
198
199
200
201
202
 
# File 'lib/iso8601/time_interval.rb', line 197

def superset?(other)
  raise(ISO8601::Errors::TypeError, "The parameter must be an instance of #{self.class}") \
    unless other.is_a?(self.class)

  include?(other.first) && include?(other.last)
end