класс ActiveSupport::TimeZone

Родитель:: Объект
Включенные модули:

Класс TimeZone служит оболочкой над экземплярами TZInfo::Timezone. Он позволяет:

Ограничить набор часовых поясов, предоставленных TZInfo, до осмысленного подмножества из 146 поясов.
Получать и отображать часовые пояса с более удобными названиями (например, «Восточное время (США и Канада)» вместо «America/New_York»).
Лениво загружать экземпляры TZInfo::Timezone только при необходимости.
Создавать экземпляры ActiveSupport::TimeWithZone с помощью методов local, parse, at и now класса TimeZone.

Если вы установите config.time_zone в приложении Rails, вы можете получить доступ к этому объекту TimeZone с помощью Time.zone.

# application.rb:
class Application < Rails::Application
  config.time_zone = 'Eastern Time (US & Canada)'
end

Time.zone      # => #<TimeZone:0x514834...>
Time.zone.name # => "Eastern Time (US & Canada)"
Time.zone.now  # => Sun, 18 May 2008 14:30:44 EDT -04:00

Версия TZInfo, входящая в состав Active Support, содержит только определения, необходимые для поддержки часовых поясов, определённых классом TimeZone. Если вам нужно использовать часовые пояса, которые не определены классом TimeZone, вам необходимо установить gem TZInfo (если установлена последняя версия gem локально, она будет использоваться вместо встроенной версии).

Константы

MAPPING: Ключи — имена часовых поясов Rails TimeZone, значения — идентификаторы TZInfo.
UTC_OFFSET_WITHOUT_COLON
UTC_OFFSET_WITH_COLON

Атрибуты

name[R]

tzinfo[R]

Публичные методы класса

[](arg) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 239
def [](arg)
  case arg
    when String
    begin
      @lazy_zones_map[arg] ||= create(arg).tap { |tz| tz.utc_offset }
    rescue TZInfo::InvalidTimezoneIdentifier
      nil
    end
    when Numeric, ActiveSupport::Duration
      arg *= 3600 if arg.abs <= 13
      all.find { |z| z.utc_offset == arg.to_i }
    else
      raise ArgumentError, "invalid argument to TimeZone[]: #{arg.inspect}"
  end
end

Найти определённый объект часового пояса. Если аргумент является строкой, он интерпретируется как имя часового пояса для поиска. Если это числовое значение, это либо смещение по часам, либо смещение по секундам часового пояса для поиска. (Будет возвращён первый с этим смещением). Возвращает nil, если такой часовой пояс не известен системе.

all() Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 223
def all
  @zones ||= zones_map.values.sort
end

Возвращает массив всех объектов TimeZone. В большинстве случаев существует несколько объектов TimeZone на каждый часовой пояс, чтобы пользователям было проще найти свой часовой пояс.

create(name)

Псевдоним для: new

find_tzinfo(name) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 207
def find_tzinfo(name)
  TZInfo::TimezoneProxy.new(MAPPING[name] || name)
end

new(name, utc_offset = nil, tzinfo = nil) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 270
def initialize(name, utc_offset = nil, tzinfo = nil)
  @name = name
  @utc_offset = utc_offset
  @tzinfo = tzinfo || TimeZone.find_tzinfo(name)
end

Создаёт новый объект TimeZone с заданным именем и смещением. Смещение — это количество секунд, на которое этот часовой пояс смещён от UTC (GMT). Секунды были выбраны как единица смещения, потому что Руби использует эту единицу для представления смещений часовых поясов (см. Time#utc_offset).

new(name) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 216
def new(name)
  self[name]
end

Возвращает экземпляр TimeZone с заданным именем или nil, если такой экземпляр TimeZone не существует. (Это необходимо для поддержки использования этого класса с макросом composed_of).

Также псевдоним для: create

seconds_to_utc_offset(seconds, colon = true) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 199
def seconds_to_utc_offset(seconds, colon = true)
  format = colon ? UTC_OFFSET_WITH_COLON : UTC_OFFSET_WITHOUT_COLON
  sign = (seconds < 0 ? '-' : '+')
  hours = seconds.abs / 3600
  minutes = (seconds.abs % 3600) / 60
  format % [sign, hours, minutes]
end

Предполагает, что self представляет смещение от UTC в секундах (как возвращается Time#utc_offset) и преобразует его в строку формата +HH:MM.

TimeZone.seconds_to_utc_offset(-21_600) # => "-06:00"

us_zones() Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 257
def us_zones
  @us_zones ||= all.find_all { |z| z.name =~ /US|Arizona|Indiana|Hawaii|Alaska/ }
end

Метод для удобства возвращения коллекции объектов TimeZone для часовых поясов в США.

Общедоступные методы экземпляров

<=>(zone) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 297
def <=>(zone)
  return unless zone.respond_to? :utc_offset
  result = (utc_offset <=> zone.utc_offset)
  result = (name <=> zone.name) if result == 0
  result
end

Сравнивает данное часовое пояс с переданным в качестве параметра. Сначала сравниваются смещения, а затем имена.

=~(re) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 306
def =~(re)
  re === name || re === MAPPING[name]
end

Сравнивает имя и идентификатор TZInfo с переданным регулярным выражением, возвращая true в случае совпадения.

at(secs) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 331
def at(secs)
  Time.at(secs).utc.in_time_zone(self)
end

Метод для создания нового экземпляра ActiveSupport::TimeWithZone в часовом поясе self по числу секунд с начала эпохи Unix.

Time.zone = 'Hawaii'        # => "Hawaii"
Time.utc(2000).to_f         # => 946684800.0
Time.zone.at(946684800.0)   # => Fri, 31 Dec 1999 14:00:00 HST -10:00

formatted_offset(colon=true, alternate_utc_string = nil) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 291
def formatted_offset(colon=true, alternate_utc_string = nil)
  utc_offset == 0 && alternate_utc_string || self.class.seconds_to_utc_offset(utc_offset, colon)
end

Возвращает смещение данного часового пояса в формате строки, например «+HH:MM».

local(*args) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 320
def local(*args)
  time = Time.utc(*args)
  ActiveSupport::TimeWithZone.new(nil, self, time)
end

Метод для создания нового экземпляра ActiveSupport::TimeWithZone в часовом поясе self из заданных значений.

Time.zone = 'Hawaii'                    # => "Hawaii"
Time.zone.local(2007, 2, 1, 15, 30, 45) # => Thu, 01 Feb 2007 15:30:45 HST -10:00

local_to_utc(time, dst=true) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 405
def local_to_utc(time, dst=true)
  tzinfo.local_to_utc(time, dst)
end

Корректирует заданное время до одновременного времени в UTC. Возвращает экземпляр Time.utc().

now() Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 377
def now
  time_now.utc.in_time_zone(self)
end

Возвращает экземпляр ActiveSupport::TimeWithZone, представляющий текущее время в часовом поясе self.

Time.zone = 'Hawaii'  # => "Hawaii"
Time.zone.now         # => Wed, 23 Jan 2008 20:24:27 HST -10:00

parse(str, now=now()) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 351
def parse(str, now=now())
  parts = Date._parse(str, false)
  return if parts.empty?

  time = Time.new(
    parts.fetch(:year, now.year),
    parts.fetch(:mon, now.month),
    parts.fetch(:mday, parts[:year] || parts[:mon] ? 1 : now.day),
    parts.fetch(:hour, 0),
    parts.fetch(:min, 0),
    parts.fetch(:sec, 0) + parts.fetch(:sec_fraction, 0),
    parts.fetch(:offset, 0)
  )

  if parts[:offset]
    TimeWithZone.new(time.utc, self)
  else
    TimeWithZone.new(nil, self, time)
  end
end

Метод для создания нового экземпляра ActiveSupport::TimeWithZone в часовом поясе self из разобранной строки.

Time.zone = 'Hawaii'                   # => "Hawaii"
Time.zone.parse('1999-12-31 14:00:00') # => Fri, 31 Dec 1999 14:00:00 HST -10:00

Если верхние компоненты отсутствуют в строке, они берутся из #now:

Time.zone.now               # => Fri, 31 Dec 1999 14:00:00 HST -10:00
Time.zone.parse('22:30:00') # => Fri, 31 Dec 1999 22:30:00 HST -10:00

Однако, если компонент даты не указан, но указаны любые другие верхние компоненты, то день месяца по умолчанию равен 1:

Time.zone.parse('Mar 2000') # => Wed, 01 Mar 2000 00:00:00 HST -10:00

period_for_local(time, dst=true) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 417
def period_for_local(time, dst=true)
  tzinfo.period_for_local(time, dst)
end

Доступно для того, чтобы экземпляры TimeZone реагировали как экземпляры TZInfo::Timezone.

period_for_utc(time) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 411
def period_for_utc(time)
  tzinfo.period_for_utc(time)
end

Доступно для того, чтобы экземпляры TimeZone реагировали как экземпляры TZInfo::Timezone.

to_s() Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 311
def to_s
  "(GMT#{formatted_offset}) #{name}"
end

Возвращает текстовое представление данного часового пояса.

today() Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 382
def today
  tzinfo.now.to_date
end

Возвращает текущую дату в этом часовом поясе.

tomorrow() Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 387
def tomorrow
  today + 1
end

Возвращает следующую дату в этом часовом поясе.

utc_offset() Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 281
def utc_offset
  if @utc_offset
    @utc_offset
  else
    tzinfo.current_period.utc_offset if tzinfo && tzinfo.current_period
  end
end

Возвращает смещение данного часового пояса от UTC в секундах.

utc_to_local(time) Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 399
def utc_to_local(time)
  tzinfo.utc_to_local(time)
end

Корректирует заданное время до одновременного времени в часовом поясе, представленном self. Возвращает экземпляр Time.utc() – если вам нужен экземпляр ActiveSupport::TimeWithZone, используйте DateAndTime::Zones#in_time_zone вместо этого.

yesterday() Показать исходный код

# File activesupport/lib/active_support/values/time_zone.rb, line 392
def yesterday
  today - 1
end

Возвращает предыдущую дату в этом часовом поясе.