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