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:



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

def initialize(input)
  case input
  when String
    parse(input)
  when Array
    from_atoms(input)
  else
    fail(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:



113
114
115
 
# File 'lib/iso8601/time_interval.rb', line 113

def first
  @first
end

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

The end time (last) of the interval.

Returns:



120
121
122
 
# File 'lib/iso8601/time_interval.rb', line 120

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



139
140
141
 
# File 'lib/iso8601/time_interval.rb', line 139

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:



45
46
47
48
 
# File 'lib/iso8601/time_interval.rb', line 45

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:



70
71
72
73
 
# File 'lib/iso8601/time_interval.rb', line 70

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

.parse(pattern) ⇒ Object

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



105
106
107
 
# File 'lib/iso8601/time_interval.rb', line 105

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

Instance Method Details

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

Parameters:

Returns:

  • (-1, 0, 1, nil) 


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

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:



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

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

#empty? ⇒ Boolean

Checks if the interval is empty.

Returns:

  • (Boolean) 


147
148
149
 
# File 'lib/iso8601/time_interval.rb', line 147

def empty?
  first == last
end

#eql?(other) ⇒ Boolean

Equality by hash.

Parameters:

Returns:

  • (Boolean) 


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

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

#hash ⇒ Fixnum

Returns:

  • (Fixnum) 


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

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:



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

def include?(other)
  fail(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:



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

def intersect?(other)
  fail(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:



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

def intersection(other)
  fail(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



127
128
129
130
131
 
# File 'lib/iso8601/time_interval.rb', line 127

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:



179
180
181
182
183
184
 
# File 'lib/iso8601/time_interval.rb', line 179

def subset?(other)
  fail(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:



195
196
197
198
199
200
 
# File 'lib/iso8601/time_interval.rb', line 195

def superset?(other)
  fail(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