123456789_123456789_123456789_123456789_123456789_

Class: TZInfo::Timestamp

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
TimestampWithOffset
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, Comparable
Inherits: Object
Defined in: lib/tzinfo/timestamp.rb

Overview

A time represented as an Integer number of seconds since 1970-01-01 00:00:00 UTC (ignoring leap seconds and using the proleptic Gregorian calendar), the fraction through the second (sub_second as a Rational) and an optional UTC offset. Like Ruby's Time class, Timestamp can distinguish between a local time with a zero offset and a time specified explicitly as UTC.

Constant Summary

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(value, sub_second = 0, utc_offset = nil) ⇒ Timestamp

Initializes a new Timestamp.

Parameters:

  • value (Integer) —

    the number of seconds since 1970-01-01 00:00:00 UTC ignoring leap seconds.

  • sub_second (Numeric) (defaults to: 0) —

    the fractional part of the second as either a Rational that is greater than or equal to 0 and less than 1, or the Integer 0.

  • utc_offset (Object) (defaults to: nil) —

    either nil for a Timestamp without a specified offset, an offset from UTC specified as an Integer number of seconds or the Symbol :utc).

Raises:

  • (ArgumentError) —

    if value is not an Integer.

  • (ArgumentError) —

    if sub_second is not a Rational, or the Integer 0.

  • (RangeError) —

    if sub_second is a Rational but that is less than 0 or greater than or equal to 1.

  • (ArgumentError) —

    if utc_offset is not nil, not an Integer and not the Symbol :utc.

[ GitHub ] 

  


# File 'lib/tzinfo/timestamp.rb', line 344



def initialize(value, sub_second = 0, utc_offset = nil)
  raise ArgumentError, 'value must be an Integer' unless value.kind_of?(Integer)
  raise ArgumentError, 'sub_second must be a Rational or the Integer 0' unless (sub_second.kind_of?(Integer) && sub_second == 0) || sub_second.kind_of?(Rational)
  raise RangeError, 'sub_second must be >= 0 and < 1' if sub_second < 0 || sub_second >= 1
  raise ArgumentError, 'utc_offset must be an Integer, :utc or nil' if utc_offset && utc_offset != :utc && !utc_offset.kind_of?(Integer)
  initialize!(value, sub_second, utc_offset)
end


  







Class Method Details



  

    .create(year, month = 1, day = 1, hour = 0, minute = 0, second = 0, sub_second = 0, utc_offset = nil)  ⇒ Timestamp 
  



  

    
Returns a new Timestamp representing the (proleptic Gregorian
calendar) date and time specified by the supplied parameters.



If utc_offset is nil, :utc or 0, the date and time parameters will
be interpreted as representing a UTC date and time. Otherwise the date
and time parameters will be interpreted as a local date and time with
the given offset.


  





  
Parameters:


    
  
  • 
    year
    (Integer)
—    
    the year.
    

    
  
    • 
  
  • 
    month
    (Integer)
    (defaults to: 1)
—    
    the month (1-12).
    

    
  
    • 
  
  • 
    day
    (Integer)
    (defaults to: 1)
—    
    the day of the month (1-31).
    

    
  
    • 
  
  • 
    hour
    (Integer)
    (defaults to: 0)
—    
    the hour (0-23).
    

    
  
    • 
  
  • 
    minute
    (Integer)
    (defaults to: 0)
—    
    the minute (0-59).
    

    
  
    • 
  
  • 
    second
    (Integer)
    (defaults to: 0)
—    
    the second (0-59).
    

    
  
    • 
  
  • 
    sub_second
    (Numeric)
    (defaults to: 0)
—    
    the fractional part of the second as either
a Rational that is greater than or equal to 0 and less than 1, or
the Integer 0.
    

    
  
    • 
  
  • 
    utc_offset
    (Object)
    (defaults to: nil)
—    
    either nil for a Timestamp without a
specified offset, an offset from UTC specified as an Integer number
of seconds or the Symbol :utc).
    

    
  
    • 



Returns:


    
  
  • 
    (Timestamp)
—    
    a new Timestamp representing the specified
(proleptic Gregorian calendar) date and time.
    

    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
—    
    if either of year, month, day, hour,
minute, or second is not an Integer.
    

    
  
    • 
  
  • 
    (ArgumentError)
—    
    if sub_second is not a Rational, or the
Integer 0.
    

    
  
    • 
  
  • 
    (ArgumentError)
—    
    if utc_offset is not nil, not an Integer
and not the Symbol :utc.
    

    
  
    • 
  
  • 
    (RangeError)
—    
    if month is not between 1 and 12.
    

    
  
    • 
  
  • 
    (RangeError)
—    
    if day is not between 1 and 31.
    

    
  
    • 
  
  • 
    (RangeError)
—    
    if hour is not between 0 and 23.
    

    
  
    • 
  
  • 
    (RangeError)
—    
    if minute is not between 0 and 59.
    

    
  
    • 
  
  • 
    (RangeError)
—    
    if second is not between 0 and 59.
    

    
  
    • 
  
  • 
    (RangeError)
—    
    if sub_second is a Rational but that is less
than 0 or greater than or equal to 1.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 55



def create(year, month = 1, day = 1, hour = 0, minute = 0, second = 0, sub_second = 0, utc_offset = nil)
  raise ArgumentError, 'year must be an Integer' unless year.kind_of?(Integer)
  raise ArgumentError, 'month must be an Integer' unless month.kind_of?(Integer)
  raise ArgumentError, 'day must be an Integer' unless day.kind_of?(Integer)
  raise ArgumentError, 'hour must be an Integer' unless hour.kind_of?(Integer)
  raise ArgumentError, 'minute must be an Integer' unless minute.kind_of?(Integer)
  raise ArgumentError, 'second must be an Integer' unless second.kind_of?(Integer)
  raise RangeError, 'month must be between 1 and 12' if month < 1 || month > 12
  raise RangeError, 'day must be between 1 and 31' if day < 1 || day > 31
  raise RangeError, 'hour must be between 0 and 23' if hour < 0 || hour > 23
  raise RangeError, 'minute must be between 0 and 59' if minute < 0 || minute > 59
  raise RangeError, 'second must be between 0 and 59' if second < 0 || second > 59

  # Based on days_from_civil from https://howardhinnant.github.io/date_algorithms.html#days_from_civil
  after_february = month > 2
  year -= 1 unless after_february
  era = year / 400
  year_of_era = year - era * 400
  day_of_year = (153 * (month + (after_february ? -3 : 9)) + 2) / 5 + day - 1
  day_of_era = year_of_era * 365 + year_of_era / 4 - year_of_era / 100 + day_of_year
  days_since_epoch = era * 146097 + day_of_era - 719468
  value = ((days_since_epoch * 24 + hour) * 60 + minute) * 60 + second
  value -= utc_offset if utc_offset.kind_of?(Integer)

  new(value, sub_second, utc_offset)
end


  








  

    .for(value, offset = :preserve) {|timestamp| ... } ⇒ Object 
  



  

    
When used without a block, returns a Timestamp representation of a
given Time, DateTime or Timestamp.



When called with a block, the Timestamp representation of value is
passed to the block. The block must then return a Timestamp, which
will be converted back to the type of the initial value. If the initial
value was a Timestamp, the block result will be returned. If the
initial value was a DateTime, a Gregorian DateTime will be returned.



The UTC offset of value can either be preserved (the Timestamp
representation will have the same UTC offset as value), ignored (the
Timestamp representation will have no defined UTC offset), or treated
as though it were UTC (the Timestamp representation will have a
#utc_offset of 0 and #utc? will return true).


  





  
Parameters:


    
  
  • 
    value
    (Object)
—    
    a Time, DateTime or Timestamp.
    

    
  
    • 
  
  • 
    offset
    (Symbol)
    (defaults to: :preserve)
—    
    either :preserve to preserve the offset of
value, :ignore to ignore the offset of value and create a
Timestamp with an unspecified offset, or :treat_as_utc to treat
the offset of value as though it were UTC and create a UTC
Timestamp.
    

    
  
    • 



Yields:


    
  
  • 
    (timestamp)
—    
    if a block is provided, the Timestamp
representation is passed to the block.
    

    
  
    • 



Yield Parameters:


    
  
  • 
    timestamp
    (Timestamp)
—    
    the Timestamp representation of
value.
    

    
  
    • 



Yield Returns:


    
  
  • 
    (Timestamp)
—    
    a Timestamp to be converted back to the type
of value.
    

    
  
    • 



Returns:


    
  
  • 
    (Object)
—    
    if called without a block, the Timestamp
representation of value, otherwise the result of the block,
converted back to the type of value.
    

    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 112



def for(value, offset = :preserve)
  raise ArgumentError, 'value must be specified' unless value

  case offset
    when :ignore
      ignore_offset = true
      target_utc_offset = nil
    when :treat_as_utc
      ignore_offset = true
      target_utc_offset = :utc
    when :preserve
      ignore_offset = false
      target_utc_offset = nil
    else
      raise ArgumentError, 'offset must be :preserve, :ignore or :treat_as_utc'
  end

  time_like = false
  timestamp = case value
    when Time
      for_time(value, ignore_offset, target_utc_offset)
    when DateTime
      for_datetime(value, ignore_offset, target_utc_offset)
    when Timestamp
      for_timestamp(value, ignore_offset, target_utc_offset)
    else
      raise ArgumentError, "#{value.class} values are not supported" unless is_time_like?(value)
      time_like = true
      for_time_like(value, ignore_offset, target_utc_offset)
  end

  if block_given?
    result = yield timestamp
    raise ArgumentError, 'block must return a Timestamp' unless result.kind_of?(Timestamp)

    case value
      when Time
        result.to_time
      when DateTime
        result.to_datetime
      else # A Time-like value or a Timestamp
        time_like ? result.to_time : result
    end
  else
    timestamp
  end
end


  








  

    .for_datetime(datetime, ignore_offset, target_utc_offset)  ⇒ Timestamp  (private)
  



  

    
Creates a Timestamp that represents a given DateTime, optionally
ignoring the offset.


  





  
Parameters:


    
  
  • 
    datetime
    (DateTime)
—    
    a DateTime.
    

    
  
    • 
  
  • 
    ignore_offset
    (Boolean)
—    
    whether to ignore the offset of
datetime.
    

    
  
    • 
  
  • 
    target_utc_offset
    (Object)
—    
    if ignore_offset is true, the UTC
offset of the result (:utc, nil or an Integer).
    

    
  
    • 



Returns:


    
  
  • 
    (Timestamp)
—    
    the Timestamp representation of datetime.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 231



def for_datetime(datetime, ignore_offset, target_utc_offset)
  value = (datetime.jd - JD_EPOCH) * 86400 + datetime.sec + datetime.min * 60 + datetime.hour * 3600
  sub_second = datetime.sec_fraction

  if ignore_offset
    utc_offset = target_utc_offset
  else
    utc_offset = (datetime.offset * 86400).to_i
    value -= utc_offset
  end

  new!(value, sub_second, utc_offset)
end


  








  

    .for_time(time, ignore_offset, target_utc_offset)  ⇒ Timestamp  (private)
  



  

    
Creates a Timestamp that represents a given Time, optionally
ignoring the offset.


  





  
Parameters:


    
  
  • 
    time
    (Time)
—    
    a Time.
    

    
  
    • 
  
  • 
    ignore_offset
    (Boolean)
—    
    whether to ignore the offset of time.
    

    
  
    • 
  
  • 
    target_utc_offset
    (Object)
—    
    if ignore_offset is true, the UTC
offset of the result (:utc, nil or an Integer).
    

    
  
    • 



Returns:


    
  
  • 
    (Timestamp)
—    
    the Timestamp representation of time.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 206



def for_time(time, ignore_offset, target_utc_offset)
  value = time.to_i
  sub_second = time.subsec

  if ignore_offset
    utc_offset = target_utc_offset
    value += time.utc_offset
  elsif time.utc?
    utc_offset = :utc
  else
    utc_offset = time.utc_offset
  end

  new!(value, sub_second, utc_offset)
end


  








  

    .for_time_like(time_like, ignore_offset, target_utc_offset)  ⇒ Timestamp  (private)
  



  

    
Creates a Timestamp that represents a given Time-like object,
optionally ignoring the offset (if the time_like responds to
utc_offset).


  





  
Parameters:


    
  
  • 
    time_like
    (Object)
—    
    a Time-like object.
    

    
  
    • 
  
  • 
    ignore_offset
    (Boolean)
—    
    whether to ignore the offset of time.
    

    
  
    • 
  
  • 
    target_utc_offset
    (Object)
—    
    if ignore_offset is true, the UTC
offset of the result (:utc, nil or an Integer).
    

    
  
    • 



Returns:


    
  
  • 
    (Timestamp)
—    
    the Timestamp representation of time_like.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 296



def for_time_like(time_like, ignore_offset, target_utc_offset)
  value = time_like.to_i
  sub_second = time_like.subsec.to_r

  if ignore_offset
    utc_offset = target_utc_offset
    value += time_like.utc_offset.to_i if time_like.respond_to?(:utc_offset)
  elsif time_like.respond_to?(:utc_offset)
    utc_offset = time_like.utc_offset.to_i
  else
    utc_offset = 0
  end

  new(value, sub_second, utc_offset)
end


  








  

    .for_timestamp(timestamp, ignore_offset, target_utc_offset)  ⇒ Timestamp  (private)
  



  

    
Returns a Timestamp that represents another Timestamp, optionally
ignoring the offset. If the result would be identical to value, the
same instance is returned. If the passed in value is an instance of a
subclass of Timestamp, then a new Timestamp will always be returned.


  





  
Parameters:


    
  
  • 
    timestamp
    (Timestamp)
—    
    a Timestamp.
    

    
  
    • 
  
  • 
    ignore_offset
    (Boolean)
—    
    whether to ignore the offset of
timestamp.
    

    
  
    • 
  
  • 
    target_utc_offset
    (Object)
—    
    if ignore_offset is true, the UTC
offset of the result (:utc, nil or an Integer).
    

    
  
    • 



Returns:


    
  
  • 
    (Timestamp)
—    
    a [Timestamp] representation of timestamp.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 256



def for_timestamp(timestamp, ignore_offset, target_utc_offset)
  if ignore_offset
    if target_utc_offset
      unless target_utc_offset == :utc && timestamp.utc? || timestamp.utc_offset == target_utc_offset
        return new!(timestamp.value + (timestamp.utc_offset || 0), timestamp.sub_second, target_utc_offset)
      end
    elsif timestamp.utc_offset
      return new!(timestamp.value + timestamp.utc_offset, timestamp.sub_second)
    end
  end

  unless timestamp.instance_of?(Timestamp)
    # timestamp is identical in value, sub_second and utc_offset but is a
    # subclass (i.e. TimestampWithOffset). Return a new Timestamp
    # instance.
    return new!(timestamp.value, timestamp.sub_second, timestamp.utc? ? :utc : timestamp.utc_offset)
  end

  timestamp
end


  








  

    .is_time_like?(value)  ⇒ Boolean  (private)
  



  

    
Determines if an object is like a Time (for the purposes of converting
to a Timestamp with .for), responding to to_i and subsec.


  





  
Parameters:


    
  
  • 
    value
    (Object)
—    
    an object to test.
    

    
  
    • 



Returns:


    
  
  • 
    (Boolean)
—    
    true if the object is Time-like, otherwise
false.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 283



def is_time_like?(value)
  value.respond_to?(:to_i) && value.respond_to?(:subsec)
end


  








  

    .new!(value, sub_second = 0, utc_offset = nil)  ⇒ Timestamp  (private)
  



  

    
Constructs a new instance of self (i.e. Timestamp or a subclass of
Timestamp) without validating the parameters. This method is used
internally within Timestamp to avoid the overhead of checking
parameters.


  





  
Parameters:


    
  
  • 
    value
    (Integer)
—    
    the number of seconds since 1970-01-01 00:00:00
UTC ignoring leap seconds.
    

    
  
    • 
  
  • 
    sub_second
    (Numeric)
    (defaults to: 0)
—    
    the fractional part of the second as either
a Rational that is greater than or equal to 0 and less than 1, or
the Integer 0.
    

    
  
    • 
  
  • 
    utc_offset
    (Object)
    (defaults to: nil)
—    
    either nil for a Timestamp without a
specified offset, an offset from UTC specified as an Integer number
of seconds or the Symbol :utc).
    

    
  
    • 



Returns:


    
  
  • 
    (Timestamp)
—    
    a new instance of self.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 192



def new!(value, sub_second = 0, utc_offset = nil)
  result = allocate
  result.send(:initialize!, value, sub_second, utc_offset)
  result
end


  








  

    .utc(value, sub_second = 0)  
  



  

    
Creates a new UTC Timestamp.


  





  
Parameters:


    
  
  • 
    value
    (Integer)
—    
    the number of seconds since 1970-01-01 00:00:00
UTC ignoring leap seconds.
    

    
  
    • 
  
  • 
    sub_second
    (Numeric)
    (defaults to: 0)
—    
    the fractional part of the second as either
a Rational that is greater than or equal to 0 and less than 1, or
the Integer 0.
    

    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
—    
    if value is not an Integer.
    

    
  
    • 
  
  • 
    (ArgumentError)
—    
    if sub_second is not a Rational, or the
Integer 0.
    

    
  
    • 
  
  • 
    (RangeError)
—    
    if sub_second is a Rational but that is less
than 0 or greater than or equal to 1.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 172



def utc(value, sub_second = 0)
  new(value, sub_second, :utc)
end


  







Instance Attribute Details



  

    #sub_second  ⇒ Numeric  (readonly)
  



  

    
  





  
Returns:


    
  
  • 
    (Numeric)
—    
    the fraction of a second elapsed since timestamp as
either a Rational or the Integer 0. Always greater than or equal to
0 and less than 1.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 321



attr_reader :sub_second


  








  

    #utc?  ⇒ Boolean  (readonly)
  



  

    
  





  
Returns:


    
  
  • 
    (Boolean)
—    
    true if this Timestamp represents UTC, false if
the Timestamp wasn't specified as UTC or nil if the Timestamp has
no specified offset.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 355



def utc?
  @utc
end


  








  

    #utc_offset  ⇒ Integer  (readonly)
  



  

    
  





  
Returns:


    
  
  • 
    (Integer)
—    
    the offset from UTC in seconds or nil if the
Timestamp doesn't have a specified offset.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 325



attr_reader :utc_offset


  








  

    #value  ⇒ Integer  (readonly)
  



  

    
  





  
Returns:


    
  
  • 
    (Integer)
—    
    the number of seconds since 1970-01-01 00:00:00 UTC
ignoring leap seconds (i.e. each day is treated as if it were 86,400
seconds long).
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 316



attr_reader :value


  







Instance Method Details



  

    #<=>(t)  ⇒ Integer 
  



  

    
Compares this Timestamp with another.



Timestamp instances without a defined UTC offset are not comparable with
Timestamp instances that have a defined UTC offset.


  





  
Parameters:


    
  
  • 
    t
    (Timestamp)
—    
    the Timestamp to compare this instance with.
    

    
  
    • 



Returns:


    
  
  • 
    (Integer)
—    
    -1, 0 or 1 depending if this instance is earlier, equal
or later than t respectively. Returns nil when comparing a
Timestamp that does not have a defined UTC offset with a Timestamp
that does have a defined UTC offset. Returns nil if t is not a
Timestamp.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 454



def <=>(t)
  return nil unless t.kind_of?(Timestamp)
  return nil if utc_offset && !t.utc_offset
  return nil if !utc_offset && t.utc_offset

  result = value <=> t.value
  result = sub_second <=> t.sub_second if result == 0
  result
end


  








  

    #add_and_set_utc_offset(seconds, utc_offset)  ⇒ Timestamp 
  



  

    
Adds a number of seconds to the Timestamp value, setting the UTC offset
of the result.


  





  
Parameters:


    
  
  • 
    seconds
    (Integer)
—    
    the number of seconds to be added.
    

    
  
    • 
  
  • 
    utc_offset
    (Object)
—    
    either nil for a Timestamp without a
specified offset, an offset from UTC specified as an Integer number of
seconds or the Symbol :utc).
    

    
  
    • 



Returns:


    
  
  • 
    (Timestamp)
—    
    the result of adding seconds to the
Timestamp value as a new Timestamp instance with the chosen
utc_offset.
    

    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
—    
    if seconds is not an Integer.
    

    
  
    • 
  
  • 
    (ArgumentError)
—    
    if utc_offset is not nil, not an Integer and
not the Symbol :utc.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 372



def add_and_set_utc_offset(seconds, utc_offset)
  raise ArgumentError, 'seconds must be an Integer' unless seconds.kind_of?(Integer)
  raise ArgumentError, 'utc_offset must be an Integer, :utc or nil' if utc_offset && utc_offset != :utc && !utc_offset.kind_of?(Integer)
  return self if seconds == 0 && utc_offset == (@utc ? :utc : @utc_offset)
  Timestamp.send(:new!, @value + seconds, @sub_second, utc_offset)
end


  








  

    #eql?  
  

  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 464



alias eql? ==


  








  

    #hash  ⇒ Integer 
  



  

    
  





  
Returns:


    
  
  • 
    (Integer)
—    
    a hash based on the value, sub-second and whether there
is a defined UTC offset.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 468



def hash
  [@value, @sub_second, !!@utc_offset].hash
end


  








  

    #initialize!(value, sub_second = 0, utc_offset = nil)   (private)
  



  

    
Initializes a new Timestamp without validating the parameters. This
method is used internally within Timestamp to avoid the overhead of
checking parameters.


  





  
Parameters:


    
  
  • 
    value
    (Integer)
—    
    the number of seconds since 1970-01-01 00:00:00 UTC
ignoring leap seconds.
    

    
  
    • 
  
  • 
    sub_second
    (Numeric)
    (defaults to: 0)
—    
    the fractional part of the second as either a
Rational that is greater than or equal to 0 and less than 1, or the
Integer 0.
    

    
  
    • 
  
  • 
    utc_offset
    (Object)
    (defaults to: nil)
—    
    either nil for a Timestamp without a
specified offset, an offset from UTC specified as an Integer number of
seconds or the Symbol :utc).
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 538



def initialize!(value, sub_second = 0, utc_offset = nil)
  @value = value

  # Convert Rational(0,1) to 0.
  @sub_second = sub_second == 0 ? 0 : sub_second

  if utc_offset
    @utc = utc_offset == :utc
    @utc_offset = @utc ? 0 : utc_offset
  else
    @utc = @utc_offset = nil
  end
end


  








  

    #inspect  ⇒ String 
  



  

    
  





  
Returns:


    
  
  • 
    (String)
—    
    the internal object state as a programmer-readable
String.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 474



def inspect
  "#<#{self.class}: @value=#{@value}, @sub_second=#{@sub_second}, @utc_offset=#{@utc_offset.inspect}, @utc=#{@utc.inspect}>"
end


  








  

    #new_datetime(klass = DateTime)   (protected)
  

  

    This method is for internal use only.
  



  

    
Constructs a new instance of a DateTime or DateTime-like class with
the same #value, #sub_second and #utc_offset as this Timestamp.


  





  
Parameters:


    
  
  • 
    klass
    (Class)
    (defaults to: DateTime)
—    
    the class to instantiate.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 496



def new_datetime(klass = DateTime)
  # Can't specify the start parameter unless the jd parameter is an exact number of days.
  # Use #gregorian instead.
  datetime = klass.jd(JD_EPOCH + ((@value.to_r + @sub_second) / 86400)).gregorian
  @utc_offset && @utc_offset != 0 ? datetime.new_offset(Rational(@utc_offset, 86400)) : datetime
end


  








  

    #new_time(klass = Time)   (protected)
  

  

    This method is for internal use only.
  



  

    
Creates a new instance of a Time or Time-like class matching the
#value and #sub_second of this Timestamp, but not setting the offset.


  





  
Parameters:


    
  
  • 
    klass
    (Class)
    (defaults to: Time)
—    
    the class to instantiate.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 486



def new_time(klass = Time)
  klass.at(@value, @sub_second * 1_000_000)
end


  








  

    #strftime(format)  ⇒ String 
  



  

    
Formats this Timestamp according to the directives in the given format
string.


  





  
Parameters:


    
  
  • 
    format
    (String)
—    
    the format string. Please refer to Time#strftime
for a list of supported format directives.
    

    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    the formatted Timestamp.
    

    
  
    • 



Raises:


    
  
  • 
    (ArgumentError)
—    
    if format is not specified.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 426



def strftime(format)
  raise ArgumentError, 'format must be specified' unless format
  to_time.strftime(format)
end


  








  

    #sub_second_to_s  ⇒ String  (private)
  



  

    
Converts the #sub_second value to a String suitable for appending to
the String representation of a Timestamp.


  





  
Returns:





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 518



def sub_second_to_s
  if @sub_second == 0
    ''
  else
    " #{@sub_second.numerator}/#{@sub_second.denominator}"
  end
end


  








  

    #to_datetime  ⇒ DateTime 
  



  

    
Converts this Timestamp to a Gregorian DateTime.


  





  
Returns:


    
  
  • 
    (DateTime)
—    
    a Gregorian DateTime representation of this
Timestamp. If the UTC offset of this Timestamp is not specified, a
UTC DateTime will be returned.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 406



def to_datetime
  new_datetime
end


  








  

    #to_i  ⇒ Integer 
  



  

    
Converts this Timestamp to an Integer number of seconds since
1970-01-01 00:00:00 UTC (ignoring leap seconds).


  





  
Returns:


    
  
  • 
    (Integer)
—    
    an Integer representation of this Timestamp (the
number of seconds since 1970-01-01 00:00:00 UTC ignoring leap seconds).
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 415



def to_i
  value
end


  








  

    #to_s  ⇒ String 
  



  

    
  





  
Returns:


    
  
  • 
    (String)
—    
    a String representation of this Timestamp.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 432



def to_s
  return value_and_sub_second_to_s unless @utc_offset
  return "#{value_and_sub_second_to_s} UTC" if @utc

  sign = @utc_offset >= 0 ? '+' : '-'
  min, sec = @utc_offset.abs.divmod(60)
  hour, min = min.divmod(60)

  "#{value_and_sub_second_to_s(@utc_offset)} #{sign}#{'%02d' % hour}:#{'%02d' % min}#{sec > 0 ? ':%02d' % sec : nil}#{@utc_offset != 0 ? " (#{value_and_sub_second_to_s} UTC)" : nil}"
end


  








  

    #to_time  ⇒ Time 
  



  

    
Converts this Timestamp to a Time.


  





  
Returns:


    
  
  • 
    (Time)
—    
    a Time representation of this Timestamp. If the UTC
offset of this Timestamp is not specified, a UTC Time will be
returned.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 391



def to_time
  time = new_time

  if @utc_offset && !@utc
    time.localtime(@utc_offset)
  else
    time.utc
  end
end


  








  

    #utc  ⇒ Timestamp  (readonly)
  



  

    
  





  
Returns:


    
  
  • 
    (Timestamp)
—    
    a UTC Timestamp equivalent to this instance. Returns
self if self.utc? is true.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 381



def utc
  return self if @utc
  Timestamp.send(:new!, @value, @sub_second, :utc)
end


  








  

    #value_and_sub_second_to_s(offset = 0)  ⇒ String  (private)
  



  

    
Converts the value and sub-seconds to a String, adding on the given
offset.


  





  
Parameters:


    
  
  • 
    offset
    (Integer)
    (defaults to: 0)
—    
    the offset to add to the value.
    

    
  
    • 



Returns:


    
  
  • 
    (String)
—    
    the value and sub-seconds.
    

    
  
    • 





  [ GitHub ]


  

  


# File 'lib/tzinfo/timestamp.rb', line 510



def value_and_sub_second_to_s(offset = 0)
  "#{@value + offset}#{sub_second_to_s}"
end