класс Time

Родительский класс:: Object
Подключённые модули:: Comparable

Объект Time представляет дату и время:

Time.new(2000, 1, 1, 0, 0, 0) # => 2000-01-01 00:00:00 -0600

Хотя его значение можно выразить одним числом (см. раздел Секунды от эпохи ниже), бывает удобно работать с его составляющими:

t = Time.new(-2000, 1, 1, 0, 0, 0.0)
# => -2000-01-01 00:00:00 -0600
t.year # => -2000
t.month # => 1
t.mday # => 1
t.hour # => 0
t.min # => 0
t.sec # => 0
t.subsec # => 0

t = Time.new(2000, 12, 31, 23, 59, 59.5)
# => 2000-12-31 23:59:59.5 -0600
t.year # => 2000
t.month # => 12
t.mday # => 31
t.hour # => 23
t.min # => 59
t.sec # => 59
t.subsec # => (1/2)

Секунды от эпохи

Секунды от эпохи — это точное число секунд (включая дробные доли секунды), прошедших с начала эпохи Unix — 1 января 1970 года.

Получить это значение точно можно с помощью метода Time.to_r:

Time.at(0).to_r        # => (0/1)
Time.at(0.999999).to_r # => (9007190247541737/9007199254740992)

Другие методы получения значения, такие как Time#to_i и Time#to_f, могут округлять или отбрасывать дробные доли секунды.

Разрешение времени

Объект Time, полученный от системных часов (например, с помощью метода Time.now), имеет разрешение, поддерживаемое системой.

Внутреннее представление времени

Концептуально класс Time использует рациональное значение для представления числа секунд, прошедших с эпохи — 1970-01-01 00:00:00 UTC. Ограничений диапазона или разрешения нет. Значение можно получить с помощью Time#to_r.

Класс Time всегда использует григорианский календарь. То есть используется пролептический григорианский календарь. Другие календари, например юлианский, не поддерживаются.

В реализации для представления рационального значения используется знаковое 63-битное целое число, объект Integer (Bignum) или объект Ratoinal. (Знаковое 63-битное целое число используется независимо от того, является ли среда 32- или 64-битной.) Значение представляет число наносекунд, прошедших с эпохи. Знаковое 63-битное целое число может представлять даты от 1823-11-12 до 2116-02-20. Когда используются объект Integer или Rational (для дат до 1823 года, после 2116 года или с точностью до наносекунд), Time работает медленнее, чем при использовании знакового 63-битного целого числа.

Ruby использует функцию C localtime и gmtime для преобразования числа в кортеж из 6 элементов (год, месяц, день, час, минута, секунда) и обратно. Для местного времени используется localtime, а для UTC — gmtime.

Integer и Rational не имеют ограничений диапазона, однако диапазон значений localtime и gmtime ограничен из-за типов C time_t и struct tm. При превышении этого ограничения Ruby экстраполирует функцию localtime.

time_t может представлять даты от 1901-12-14 до 2038-01-19, если это 32-битное знаковое целое число, и от -292277022657-01-27 до 292277026596-12-05, если это 64-битное знаковое целое число. Однако localtime на некоторых платформах не поддерживает отрицательные значения time_t (до 1970 года).

В struct tm есть член tm_year для представления года. (tm_year = 0 означает 1900 год.) В стандарте C он определён как int. Если int — 32-битное, tm_year может представлять годы от -2147481748 до 2147485547.

Ruby поддерживает високосные секунды, если их поддерживают функции C localtime и gmtime. В большинстве Unix-систем они используют базу данных tz. В базе данных tz есть часовые пояса, поддерживающие високосные секунды. Например, «Asia/Tokyo» не поддерживает високосные секунды, а «right/Asia/Tokyo» поддерживает. Поэтому в большинстве Unix-систем Ruby поддерживает високосные секунды, если для переменной окружения TZ установлено значение «right/Asia/Tokyo».

Примеры

Все эти примеры приведены для часового пояса EST, который отстаёт от GMT на 5 часов.

Создание нового экземпляра `Time`

Создать новый экземпляр Time можно с помощью Time.new. При этом будет использовано текущее системное время. Time.now — это псевдоним данного метода. Также методу Time.new можно передать составляющие времени: год, месяц, минуту и т. д. Чтобы создать время таким способом, необходимо указать как минимум год. Если указать только год, временем по умолчанию будет 1 января этого года, 00:00:00, в текущем системном часовом поясе. Вот несколько примеров:

Time.new(2002)         #=> 2002-01-01 00:00:00 -0500
Time.new(2002, 10)     #=> 2002-10-01 00:00:00 -0500
Time.new(2002, 10, 31) #=> 2002-10-31 00:00:00 -0500

Можно передать смещение UTC:

Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 +0200

Или объект часового пояса:

zone = timezone("Europe/Athens")      # Eastern European Time, UTC+2
Time.new(2002, 10, 31, 2, 2, 2, zone) #=> 2002-10-31 02:02:02 +0200

Также можно использовать Time.local и Time.utc, чтобы определить местный часовой пояс и часовой пояс UTC, вместо использования текущих системных настроек.

Новое время также можно создать с помощью Time.at, которому передаётся число секунд (с дробной частью), прошедших с эпохи Unix.

Time.at(628232400) #=> 1989-11-28 00:00:00 -0500

Работа с экземпляром `Time`

После создания экземпляра Time с ним можно выполнять множество действий. Ниже приведены некоторые примеры. Во всех последующих примерах будем считать, что выполнены следующие действия:

t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00")

Это был понедельник?

t.monday? #=> false

Какой это был год?

t.year #=> 1993

В это время действовало летнее время?

t.dst? #=> false

Какой день будет через год?

t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900

Сколько секунд прошло с эпохи Unix?

t.to_i #=> 730522800

Также можно выполнять стандартные операции, например сравнивать два момента времени.

t1 = Time.new(2010)
t2 = Time.new(2011)

t1 == t2 #=> false
t1 == t1 #=> true
t1 <  t2 #=> true
t1 >  t2 #=> false

Time.new(2010,10,31).between?(t1, t2) #=> true

Что здесь представлено

Сначала — о том, что описано в других разделах. Класс Time:

Наследуется от класса Object.
Подключает модуль Comparable.

Здесь класс Time предоставляет методы, полезные для:

Методы создания

::new: возвращает новый объект времени на основе указанных аргументов (год, месяц и т. д.), включая необязательное значение часового пояса.
::local (псевдоним — ::mktime): аналогичен ::new, за исключением того, что используется местный часовой пояс.
::utc (псевдоним — ::gm): аналогичен ::new, за исключением того, что используется часовой пояс UTC.
::at: возвращает новый объект времени на основе числа секунд, прошедших с эпохи.
::now: возвращает новый объект времени на основе текущего системного времени.
+ (сложение): возвращает новый объект времени, увеличенный на заданное число секунд.
- (вычитание): возвращает новый объект времени, уменьшенный на заданное число секунд.

Методы получения значений

year: возвращает год указанного времени.
month (псевдоним — mon): возвращает месяц указанного времени.
mday (псевдоним — day): возвращает день месяца.
hour: возвращает значение часа указанного времени.
min: возвращает значение минут указанного времени.
sec: возвращает значение секунд указанного времени.
usec (псевдоним — tv_usec): возвращает число микросекунд в дробной части секунд указанного времени.
nsec (псевдоним — tv_nsec: возвращает число наносекунд в дробной части секунд указанного времени.
subsec: возвращает дробную часть секунд указанного времени.
wday: возвращает целочисленное значение дня недели (0 == воскресенье).
yday: возвращает целочисленное значение дня года (1 == 1 января).
hash: возвращает целочисленное хеш-значение указанного времени.
utc_offset (псевдонимы — gmt_offset и gmtoff): возвращает смещение времени относительно UTC в секундах.
to_f: возвращает число секунд, прошедших с эпохи, в виде числа с плавающей точкой.
to_i (псевдоним — tv_sec): возвращает целое число секунд, прошедших с эпохи.
to_r: возвращает число секунд, прошедших с эпохи, в виде числа Rational.
zone: возвращает строковое представление часового пояса указанного времени.

Методы проверки

utc? (псевдоним — gmt?): возвращает признак того, что время задано в UTC.
dst? (псевдоним — isdst): возвращает признак того, что для времени действует летнее время (DST).
sunday?: возвращает признак того, что день недели — воскресенье.
monday?: возвращает признак того, что день недели — понедельник.
tuesday?: возвращает признак того, что день недели — вторник.
wednesday?: возвращает признак того, что день недели — среда.
thursday?: возвращает признак того, что день недели — четверг.
friday?: возвращает признак того, что день недели — пятница.
saturday?: возвращает признак того, что день недели — суббота.

Методы сравнения

<=>: сравнивает self с другим временем.
eql?: возвращает признак того, что время равно другому времени.

Методы преобразования

asctime (псевдоним — ctime): возвращает время в виде строки.
inspect: возвращает подробное строковое представление времени.
strftime: возвращает время в виде строки согласно заданному формату.
to_a: возвращает массив из 10 значений, полученных из времени.
to_s: возвращает строковое представление времени.
getutc (псевдоним — getgm): возвращает новый объект времени, преобразованный в UTC.
getlocal: возвращает новый объект времени, преобразованный в местное время.
utc (псевдоним — gmtime): преобразует время в UTC на месте.
localtime: преобразует время в местное на месте.
deconstruct_keys: возвращает хеш компонентов времени, используемых при сопоставлении с образцом.

Методы округления

round: возвращает новый объект времени с округлёнными дробными долями секунд.
ceil: возвращает новый объект времени, округляя дробную часть секунд вверх.
floor: возвращает новый объект времени, округляя дробную часть секунд вниз.

Формы аргумента zone описаны в разделе Спецификаторы часового пояса.

Спецификаторы часового пояса

Некоторые методы Time принимают аргументы, задающие часовой пояс:

Time.at: ключевой аргумент in:.
Time.new: позиционный аргумент zone или ключевой аргумент in:.
Time.now: ключевой аргумент in:.
Time#getlocal: позиционный аргумент zone.
Time#localtime: позиционный аргумент zone.

Передаваемое значение должно быть одним из следующих (каждый вариант подробно описан ниже):

Смещения в часах/минутах

Значением часового пояса может быть строковое смещение относительно UTC в формате '+HH:MM' или '-HH:MM', где:

HH — двузначное значение часа в диапазоне 0..23.
MM — двузначное значение минут в диапазоне 0..59.

Примеры:

t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
Time.at(t, in: '-23:59')            # => 1999-12-31 20:16:01 -2359
Time.at(t, in: '+23:59')            # => 2000-01-02 20:14:01 +2359

Однобуквенные смещения

Значением часового пояса может быть буква в диапазоне 'A'..'I' или 'K'..'Z'; см. список военных часовых поясов:

t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
Time.at(t, in: 'A')                 # => 2000-01-01 21:15:01 +0100
Time.at(t, in: 'I')                 # => 2000-01-02 05:15:01 +0900
Time.at(t, in: 'K')                 # => 2000-01-02 06:15:01 +1000
Time.at(t, in: 'Y')                 # => 2000-01-01 08:15:01 -1200
Time.at(t, in: 'Z')                 # => 2000-01-01 20:15:01 UTC

Целочисленные смещения

Значением часового пояса может быть целое число секунд в диапазоне -86399..86399:

t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
Time.at(t, in: -86399)              # => 1999-12-31 20:15:02 -235959
Time.at(t, in: 86399)               # => 2000-01-02 20:15:00 +235959

Объекты часового пояса

Значением часового пояса может быть объект, отвечающий на определённые методы часового пояса, например экземпляр Timezone или TZInfo.

Методы часового пояса:

local_to_utc:

Вызывается, когда Time.new вызывается со значением tz для позиционного аргумента zone или ключевого аргумента in:.

Аргумент

объект типа Time.

Возвращает

объект типа Time в часовом поясе UTC.
utc_to_local:

Вызывается, когда Time.at или Time.now вызывается со значением tz для ключевого аргумента in:, а также когда Time#getlocal или Time#localtime вызывается со значением tz для позиционного аргумента zone.

Смещение UTC вычисляется как разница между исходным временем и возвращённым объектом в виде Integer. Если объект использует фиксированное смещение, также учитывается его utc_offset.

Аргумент

объект типа Time.

Возвращает

объект типа Time в местном часовом поясе.

Пользовательский класс часового пояса может иметь следующие методы экземпляра, которые будут вызваны, если они определены:

abbr:

Вызывается, когда Time#strftime вызывается с форматом, содержащим %Z.

Аргумент

объект типа Time.

Возвращает

строковое сокращённое название часового пояса.
dst?:

Вызывается, когда Time.at или Time.now вызывается со значением tz для ключевого аргумента in:, а также когда Time#getlocal или Time#localtime вызывается со значением tz для позиционного аргумента zone.

Аргумент

объект типа Time.

Возвращает

признак того, что для времени действует летнее время.
name:

Вызывается при вызове Marshal.dump(t).

Аргумент

отсутствует.

Возвращает

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

Объекты типа `Time`

Объект типа Time — это контейнер, способный взаимодействовать с библиотеками часовых поясов для преобразования часового пояса.

Аргумент методов преобразования часового пояса, описанных выше, будет иметь атрибуты, аналогичные атрибутам Time, за исключением того, что атрибуты, связанные с часовым поясом, не имеют значения.

Объекты, возвращаемые методами local_to_utc и utc_to_local объекта часового пояса, могут относиться к тому же классу, что и их аргументы, к произвольным классам объектов или к классу Integer.

Если возвращаемый объект принадлежит не классу Integer, его класс должен иметь следующие методы:

year
mon
mday
hour
min
sec
isdst
to_i

Компоненты возвращённого объекта Integer, разложенные в UTC, интерпретируются как время в указанном часовом поясе.

Названия часовых поясов

Если у класса (получателя методов класса или класса получателя методов экземпляра) есть синглтон-метод find_timezone, он вызывается для получения соответствующего объекта часового пояса по названию часового пояса.

Например, с использованием Timezone:

class TimeWithTimezone < Time
  require 'timezone'
  def self.find_timezone(z) = Timezone[z]
end

TimeWithTimezone.now(in: "America/New_York")        #=> 2023-12-25 00:00:00 -0500
TimeWithTimezone.new("2023-12-25 America/New_York") #=> 2023-12-25 00:00:00 -0500

Или с использованием TZInfo:

class TimeWithTZInfo < Time
  require 'tzinfo'
  def self.find_timezone(z) = TZInfo::Timezone.get(z)
end

TimeWithTZInfo.now(in: "America/New_York")          #=> 2023-12-25 00:00:00 -0500
TimeWithTZInfo.new("2023-12-25 America/New_York")   #=> 2023-12-25 00:00:00 -0500

Этот метод можно определить для отдельных подклассов или для класса Time верхнего уровня.

Открытые методы класса

at (time, subsec = false, unit = :microsecond, in: nil) Показать исходный код

# File timev.rb, line 329
def self.at(time, subsec = false, unit = :microsecond, in: nil)
  if Primitive.mandatory_only?
    Primitive.time_s_at1(time)
  else
    Primitive.time_s_at(time, subsec, unit, Primitive.arg!(:in))
  end
end

Возвращает новый объект Time на основе заданных аргументов.

Обязательный аргумент time может быть одним из следующих:

Объект Time, значение которого используется как основа для возвращаемого времени; на него также влияет необязательный именованный аргумент in: (см. ниже).
Числовое значение, задающее количество секунд эпохи для возвращаемого времени.

Примеры:

t = Time.new(2000, 12, 31, 23, 59, 59) # => 2000-12-31 23:59:59 -0600
secs = t.to_i                          # => 978328799
Time.at(secs)                          # => 2000-12-31 23:59:59 -0600
Time.at(secs + 0.5)                    # => 2000-12-31 23:59:59.5 -0600
Time.at(1000000000)                    # => 2001-09-08 20:46:40 -0500
Time.at(0)                             # => 1969-12-31 18:00:00 -0600
Time.at(-1000000000)                   # => 1938-04-24 17:13:20 -0500

Необязательный числовой аргумент subsec и необязательный символьный аргумент units используются вместе для задания долей секунды возвращаемого времени; аргумент units задаёт единицы измерения для subsec:

:millisecond: subsec в миллисекундах:

Time.at(secs, 0, :millisecond)     # => 2000-12-31 23:59:59 -0600
Time.at(secs, 500, :millisecond)   # => 2000-12-31 23:59:59.5 -0600
Time.at(secs, 1000, :millisecond)  # => 2001-01-01 00:00:00 -0600
Time.at(secs, -1000, :millisecond) # => 2000-12-31 23:59:58 -0600

:microsecond или :usec: subsec в микросекундах:

Time.at(secs, 0, :microsecond)        # => 2000-12-31 23:59:59 -0600
Time.at(secs, 500000, :microsecond)   # => 2000-12-31 23:59:59.5 -0600
Time.at(secs, 1000000, :microsecond)  # => 2001-01-01 00:00:00 -0600
Time.at(secs, -1000000, :microsecond) # => 2000-12-31 23:59:58 -0600

:nanosecond или :nsec: subsec в наносекундах:

Time.at(secs, 0, :nanosecond)           # => 2000-12-31 23:59:59 -0600
Time.at(secs, 500000000, :nanosecond)   # => 2000-12-31 23:59:59.5 -0600
Time.at(secs, 1000000000, :nanosecond)  # => 2001-01-01 00:00:00 -0600
Time.at(secs, -1000000000, :nanosecond) # => 2000-12-31 23:59:58 -0600

Необязательный именованный аргумент in: zone задаёт часовой пояс возвращаемого времени:

Time.at(secs, in: '+12:00') # => 2001-01-01 17:59:59 +1200
Time.at(secs, in: '-12:00') # => 2000-12-31 17:59:59 -1200

Варианты аргумента zone см. в разделе Обозначения часовых поясов.

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

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

# File lib/time.rb, line 572
def httpdate(date)
  if date.match?(/\A\s*
      (?:Mon|Tue|Wed|Thu|Fri|Sat|Sun),\x20
      (\d{2})\x20
      (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\x20
      (\d{4})\x20
      (\d{2}):(\d{2}):(\d{2})\x20
      GMT
      \s*\z/ix)
    self.rfc2822(date).utc
  elsif /\A\s*
         (?:Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday),\x20
         (\d\d)-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-(\d\d)\x20
         (\d\d):(\d\d):(\d\d)\x20
         GMT
         \s*\z/ix =~ date
    year = $3.to_i
    if year < 50
      year += 2000
    else
      year += 1900
    end
    self.utc(year, $2, $1.to_i, $4.to_i, $5.to_i, $6.to_i)
  elsif /\A\s*
         (?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)\x20
         (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\x20
         (\d\d|\x20\d)\x20
         (\d\d):(\d\d):(\d\d)\x20
         (\d{4})
         \s*\z/ix =~ date
    self.utc($6.to_i, MonthValue[$1.upcase], $2.to_i,
             $3.to_i, $4.to_i, $5.to_i)
  else
    raise ArgumentError.new("not RFC 2616 compliant date: #{date.inspect}")
  end
end

Разбирает date как дату HTTP, определённую RFC 2616, и преобразует её в объект Time.

Возникает исключение ArgumentError, если date не соответствует RFC 2616 или если класс Time не может представить указанную дату.

Дополнительные сведения об этом формате см. в разделе httpdate.

require 'time'

Time.httpdate("Thu, 06 Oct 2011 02:26:12 GMT")
#=> 2011-10-06 02:26:12 UTC

Чтобы использовать этот метод, необходимо подключить библиотеку ‘time’.

iso8601 (time)

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

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

# File ext/json/lib/json/add/time.rb, line 9
def self.json_create(object)
  if usec = object.delete('u') # used to be tv_usec -> tv_nsec
    object['n'] = usec * 1000
  end
  at(object['s'], Rational(object['n'], 1000))
end

См. as_json.

local(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0) → new_time Показать исходный код

local(sec, min, hour, mday, month, year, dummy, dummy, dummy, dummy) → new_time

static VALUE
time_s_mktime(int argc, VALUE *argv, VALUE klass)
{
    struct vtm vtm;

    time_arg(argc, argv, &vtm);
    return time_localtime(time_new_timew(klass, timelocalw(&vtm)));
}

Работает как Time.utc, но возвращаемый объект Time использует местный часовой пояс, а не часовой пояс UTC:

# With seven arguments.
Time.local(0, 1, 2, 3, 4, 5, 6)
# => 0000-01-02 03:04:05.000006 -0600
# With exactly ten arguments.
Time.local(0, 1, 2, 3, 4, 5, 6, 7, 8, 9)
# => 0005-04-03 02:01:00 -0600

Также имеет псевдоним: mktime

mktime

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

new(year = nil, mon = nil, mday = nil, hour = nil, min = nil, sec = nil, zone = nil, in: nil, precision: 9) Показать исходный код

# File timev.rb, line 440
def initialize(year = (now = true), mon = (str = year; nil), mday = nil, hour = nil, min = nil, sec = nil, zone = nil,
               in: nil, precision: 9)
  if zone
    if Primitive.arg!(:in)
      raise ArgumentError, "timezone argument given as positional and keyword arguments"
    end
  else
    zone = Primitive.arg!(:in)
  end

  if now
    return Primitive.time_init_now(zone)
  end

  if str and Primitive.time_init_parse(str, zone, precision)
    return self
  end

  Primitive.time_init_args(year, mon, mday, hour, min, sec, zone)
end

Возвращает новый объект Time на основе заданных аргументов; по умолчанию используется местный часовой пояс.

Если позиционные аргументы не заданы, возвращает значение Time.now:

Time.new # => 2021-04-24 17:27:46.0512465 -0500

Если задан один строковый аргумент, представляющий время, возвращает новый объект Time на основе этого аргумента с местным часовым поясом.

Time.new('2000-12-31 23:59:59.5')              # => 2000-12-31 23:59:59.5 -0600
Time.new('2000-12-31 23:59:59.5 +0900')        # => 2000-12-31 23:59:59.5 +0900
Time.new('2000-12-31 23:59:59.5', in: '+0900') # => 2000-12-31 23:59:59.5 +0900
Time.new('2000-12-31 23:59:59.5')              # => 2000-12-31 23:59:59.5 -0600
Time.new('2000-12-31 23:59:59.56789', precision: 3) # => 2000-12-31 23:59:59.567 -0600

Если задано от одного до шести аргументов, возвращает новый объект Time на основе этих аргументов с местным часовым поясом.

Time.new(2000, 1, 2, 3, 4, 5) # => 2000-01-02 03:04:05 -0600

Для позиционных аргументов (кроме zone):

year: год без ограничений диапазона:

Time.new(999999999)  # => 999999999-01-01 00:00:00 -0600
Time.new(-999999999) # => -999999999-01-01 00:00:00 -0600

month: месяц в диапазоне (1..12) или название месяца из трёх букв без учёта регистра:

Time.new(2000, 1)     # => 2000-01-01 00:00:00 -0600
Time.new(2000, 12)    # => 2000-12-01 00:00:00 -0600
Time.new(2000, 'jan') # => 2000-01-01 00:00:00 -0600
Time.new(2000, 'JAN') # => 2000-01-01 00:00:00 -0600

mday: день месяца в диапазоне (1..31):

Time.new(2000, 1, 1)  # => 2000-01-01 00:00:00 -0600
Time.new(2000, 1, 31) # => 2000-01-31 00:00:00 -0600

hour: час в диапазоне (0..23) или 24, если min, sec и usec равны нулю:

Time.new(2000, 1, 1, 0)  # => 2000-01-01 00:00:00 -0600
Time.new(2000, 1, 1, 23) # => 2000-01-01 23:00:00 -0600
Time.new(2000, 1, 1, 24) # => 2000-01-02 00:00:00 -0600

min: минута в диапазоне (0..59):

Time.new(2000, 1, 1, 0, 0)  # => 2000-01-01 00:00:00 -0600
Time.new(2000, 1, 1, 0, 59) # => 2000-01-01 00:59:00 -0600

sec: секунда в диапазоне (0…61):

Time.new(2000, 1, 1, 0, 0, 0)  # => 2000-01-01 00:00:00 -0600
Time.new(2000, 1, 1, 0, 0, 59) # => 2000-01-01 00:00:59 -0600
Time.new(2000, 1, 1, 0, 0, 60) # => 2000-01-01 00:01:00 -0600

sec может быть Float или Rational.

Time.new(2000, 1, 1, 0, 0, 59.5)  # => 2000-12-31 23:59:59.5 +0900
Time.new(2000, 1, 1, 0, 0, 59.7r) # => 2000-12-31 23:59:59.7 +0900

Эти значения могут быть представлены как:

Целые числа, как указано выше.

Числа, преобразуемые в целые:

Time.new(Float(0.0), Rational(1, 1), 1.0, 0.0, 0.0, 0.0)
# => 0000-01-01 00:00:00 -0600

Целые числа типа String:

a = %w[0 1 1 0 0 0]
# => ["0", "1", "1", "0", "0", "0"]
Time.new(*a) # => 0000-01-01 00:00:00 -0600

Если задан позиционный аргумент zone или именованный аргумент in:, новый объект Time будет использовать указанный часовой пояс. Варианты аргумента zone см. в разделе Обозначения часовых поясов:

Time.new(2000, 1, 1, 0, 0, 0, '+12:00')
# => 2000-01-01 00:00:00 +1200
Time.new(2000, 1, 1, 0, 0, 0, in: '-12:00')
# => 2000-01-01 00:00:00 -1200
Time.new(in: '-12:00')
# => 2022-08-23 08:49:26.1941467 -1200

Поскольку именованный аргумент in: лишь задаёт значение по умолчанию, если первый аргумент в виде одиночной строки содержит сведения о часовом поясе, этот именованный аргумент будет молча проигнорирован.

Time.new('2000-01-01 00:00:00 +0100', in: '-0500').utc_offset  # => 3600

precision: максимальное количество значащих цифр в дробной части секунды; по умолчанию — 9. Лишние цифры отбрасываются, как и при других операциях с Time. Игнорируется, если первый аргумент не является строкой.

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

# File timev.rb, line 270
def self.now(in: nil)
  Primitive.time_s_now(Primitive.arg!(:in))
end

Создаёт новый объект Time на основе текущего системного времени. Это то же самое, что Time.new без аргументов.

Time.now               # => 2009-06-24 12:39:54 +0900
Time.now(in: '+04:00') # => 2009-06-24 07:39:54 +0400

Варианты аргумента zone см. в разделе Обозначения часовых поясов.

parse (date, now=self.now) { |year| ... } Показать исходный код

# File lib/time.rb, line 385
def parse(date, now=self.now)
  comp = !block_given?
  d = Date._parse(date, comp)
  year = d[:year]
  year = yield(year) if year && !comp
  make_time(date, year, d[:yday], d[:mon], d[:mday], d[:hour], d[:min], d[:sec], d[:sec_fraction], d[:zone], now)
end

Принимает строковое представление объекта Time и пытается разобрать его с помощью эвристики.

Этот метод **не** выполняет проверку корректности. Если входная строка не соответствует строго допустимым форматам, результат может быть непонятным. По возможности рекомендуется использовать вместо этого метода Time.strptime.

require 'time'

Time.parse("2010-10-31") #=> 2010-10-31 00:00:00 -0500

Все отсутствующие части даты определяются на основе текущей даты.

require 'time'

# assuming the current date is "2011-10-31"
Time.parse("12:00") #=> 2011-10-31 12:00:00 -0500

Дату, используемую для определения отсутствующих элементов, можно изменить, передав второй объект, который поддерживает методы mon, day и year, например Date, Time или DateTime. Можно также использовать собственный объект.

require 'time'

class MyDate
  attr_reader :mon, :day, :year

  def initialize(mon, day, year)
    @mon, @day, @year = mon, day, year
  end
end

d  = Date.parse("2010-10-28")
t  = Time.parse("2010-10-29")
dt = DateTime.parse("2010-10-30")
md = MyDate.new(10,31,2010)

Time.parse("12:00", d)  #=> 2010-10-28 12:00:00 -0500
Time.parse("12:00", t)  #=> 2010-10-29 12:00:00 -0500
Time.parse("12:00", dt) #=> 2010-10-30 12:00:00 -0500
Time.parse("12:00", md) #=> 2010-10-31 12:00:00 -0500

Если передан блок, год, описанный в date, преобразуется этим блоком. Это предназначено специально для обработки двузначных годов. Например, чтобы считать все двузначные годы меньше 70 годами 2000+, можно написать следующее:

require 'time'

Time.parse("01-10-31") {|year| year + (year < 70 ? 2000 : 1900)}
#=> 2001-10-31 00:00:00 -0500
Time.parse("70-10-31") {|year| year + (year < 70 ? 2000 : 1900)}
#=> 1970-10-31 00:00:00 -0500

Если старшие компоненты заданного времени некорректны или отсутствуют, вместо них используются соответствующие компоненты из now. Для младших компонентов при некорректном или отсутствующем значении предполагаются минимальные значения (1 или 0). Например:

require 'time'

# Suppose it is "Thu Nov 29 14:33:20 2001" now and
# your time zone is EST which is GMT-5.
now = Time.parse("Thu Nov 29 14:33:20 2001")
Time.parse("16:30", now)     #=> 2001-11-29 16:30:00 -0500
Time.parse("7/23", now)      #=> 2001-07-23 00:00:00 -0500
Time.parse("Aug 31", now)    #=> 2001-08-31 00:00:00 -0500
Time.parse("Aug 2000", now)  #=> 2000-08-01 00:00:00 -0500

Поскольку сокращения часовых поясов, определённые на местах по всему миру, часто совпадают, этот метод не предназначен для распознавания всех таких сокращений. Например, сокращение «CST» используется в разных значениях:

-06:00 in America/Chicago,
-05:00 in America/Havana,
+08:00 in Asia/Harbin,
+09:30 in Australia/Darwin,
+10:30 in Australia/Adelaide,
etc.

Учитывая это, метод распознаёт только сокращения часовых поясов, описанные в RFC 822, и системный часовой пояс — именно в таком порядке (то есть определение в RFC 822 имеет приоритет над определением системного часового пояса). Системный часовой пояс берётся из Time.local(year, 1, 1).zone и Time.local(year, 7, 1).zone. Если извлечённое сокращение часового пояса не совпадает ни с одним из них, оно игнорируется, а заданное время считается местным.

Возникает исключение ArgumentError, если Date._parse не может извлечь данные из date или если класс Time не может представить указанную дату.

Этот метод можно использовать как резервный вариант для других методов разбора:

Time.rfc2822(date) rescue Time.parse(date)
Time.httpdate(date) rescue Time.parse(date)
Time.xmlschema(date) rescue Time.parse(date)

Однако следует проверять, не завершился ли вызов Time.parse ошибкой.

Чтобы использовать этот метод, необходимо подключить библиотеку ‘time’.

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

# File lib/time.rb, line 514
def rfc2822(date)
  if /\A\s*
      (?:(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)\s*,\s*)?
      (\d{1,2})\s+
      (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+
      (\d{2,})\s+
      (\d{2})\s*
      :\s*(\d{2})
      (?:\s*:\s*(\d\d))?\s+
      ([+-]\d{4}|
       UT|GMT|EST|EDT|CST|CDT|MST|MDT|PST|PDT|[A-IK-Z])/ix =~ date
    # Since RFC 2822 permit comments, the regexp has no right anchor.
    day = $1.to_i
    mon = MonthValue[$2.upcase]
    year = $3.to_i
    short_year_p = $3.length <= 3
    hour = $4.to_i
    min = $5.to_i
    sec = $6 ? $6.to_i : 0
    zone = $7

    if short_year_p
      # following year completion is compliant with RFC 2822.
      year = if year < 50
               2000 + year
             else
               1900 + year
             end
    end

    off = zone_offset(zone)
    year, mon, day, hour, min, sec =
      apply_offset(year, mon, day, hour, min, sec, off)
    t = self.utc(year, mon, day, hour, min, sec)
    force_zone!(t, zone, off)
    t
  else
    raise ArgumentError.new("not RFC 2822 compliant date: #{date.inspect}")
  end
end

Разбирает date как дату и время, определённые RFC 2822, и преобразует их в объект Time. Формат идентичен формату даты, определённому RFC 822 и обновлённому RFC 1123.

Возникает исключение ArgumentError, если date не соответствует RFC 2822 или если класс Time не может представить указанную дату.

Дополнительные сведения об этом формате см. в разделе rfc2822.

require 'time'

Time.rfc2822("Wed, 05 Oct 2011 22:26:12 -0400")
#=> 2010-10-05 22:26:12 -0400

Чтобы использовать этот метод, необходимо подключить библиотеку ‘time’.

Также имеет псевдоним: rfc822

rfc822 (date)

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

strptime (date, format, now=self.now) { |year| ... } Показать исходный код

# File lib/time.rb, line 462
def strptime(date, format, now=self.now)
  d = Date._strptime(date, format)
  raise ArgumentError, "invalid date or strptime format - '#{date}' '#{format}'" unless d
  if seconds = d[:seconds]
    if sec_fraction = d[:sec_fraction]
      usec = sec_fraction * 1000000
      usec *= -1 if seconds < 0
    else
      usec = 0
    end
    t = Time.at(seconds, usec)
    if zone = d[:zone]
      force_zone!(t, zone)
    end
  else
    year = d[:year]
    year = yield(year) if year && block_given?
    yday = d[:yday]
    if (d[:cwyear] && !year) || ((d[:cwday] || d[:cweek]) && !(d[:mon] && d[:mday]))
      # make_time doesn't deal with cwyear/cwday/cweek
      return Date.strptime(date, format).to_time
    end
    if (d[:wnum0] || d[:wnum1]) && !yday && !(d[:mon] && d[:mday])
      yday = Date.strptime(date, format).yday
    end
    t = make_time(date, year, yday, d[:mon], d[:mday], d[:hour], d[:min], d[:sec], d[:sec_fraction], d[:zone], now)
  end
  t
end

Работает аналогично parse, но вместо эвристического определения формата входной строки принимает второй аргумент, описывающий формат строки.

Если дата или формат некорректны, возникает исключение ArgumentError.

Если передан блок, год, описанный в date, преобразуется этим блоком. Например:

Time.strptime(...) {|y| y < 100 ? (y >= 69 ? y + 1900 : y + 2000) : y}

Ниже приведён список параметров форматирования:

%a: Сокращённое название дня недели («Sun»)
%A: Полное название дня недели («Sunday»)
%b: Сокращённое название месяца («Jan»)
%B: Полное название месяца («January»)
%c: Предпочтительное местное представление даты и времени
%C: Век (20 для 2009 года)
%d: День месяца (01..31)
%D: Дата (%m/%d/%y)
%e: День месяца с пробелом вместо ведущего нуля ( 1..31)
%F: Эквивалент %Y-%m-%d (формат даты ISO 8601)
%g: Последние две цифры коммерческого года
%G: Год по неделям согласно ISO-8601 (неделя 1 начинается в понедельник и включает 4 января)
%h: Эквивалент %b
%H: Час дня в 24-часовом формате (00..23)
%I: Час дня в 12-часовом формате (01..12)
%j: День года (001..366)
%k: Час в 24-часовом формате с пробелом вместо ведущего нуля ( 0..23)
%l: Час в 12-часовом формате с пробелом вместо ведущего нуля ( 0..12)
%L: Миллисекунда секунды (000..999)
%m: Месяц года (01..12)
%M: Минута часа (00..59)
%n: Символ новой строки (n)
%N: Цифры дробной части секунды
%p: Обозначение времени суток («AM» или «PM»)
%P: Обозначение времени суток («am» или «pm»)
%r: Время в 12-часовом формате (то же, что %I:%M:%S %p)
%R: Время в 24-часовом формате (%H:%M)
%s: Количество секунд с 1970-01-01 00:00:00 UTC.
%S: Секунда минуты (00..60)
%t: Символ табуляции (t)
%T: Время в 24-часовом формате (%H:%M:%S)
%u: День недели в виде десятичного числа; понедельник — 1. (1..7)
%U: Номер недели текущего года, где первая неделя начинается с первого воскресенья (00..53)
%v: Дата в формате VMS (%e-%b-%Y)
%V: Номер недели года согласно ISO 8601 (01..53)
%W: Номер недели текущего года, где первая неделя начинается с первого понедельника (00..53)
%w: День недели (воскресенье — 0, 0..6)
%x: Предпочтительное представление только даты, без времени
%X: Предпочтительное представление только времени, без даты
%y: Год без указания века (00..99)
%Y: Год, который может включать век, если он указан
%z: Часовой пояс в виде смещения от UTC в часах (например, +0900)
%Z: Название часового пояса
%%: Символ «%»
%+: date(1) (%a %b %e %H:%M:%S %Z %Y)

require 'time'

Time.strptime("2000-10-31", "%Y-%m-%d") #=> 2000-10-31 00:00:00 -0500

Чтобы использовать этот метод, необходимо подключить библиотеку ‘time’.

utc(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0) → new_time Показать исходный код

utc(sec, min, hour, mday, month, year, dummy, dummy, dummy, dummy) → new_time

static VALUE
time_s_mkutc(int argc, VALUE *argv, VALUE klass)
{
    struct vtm vtm;

    time_arg(argc, argv, &vtm);
    return time_gmtime(time_new_timew(klass, timegmw(&vtm)));
}

Возвращает новый объект Time на основе заданных аргументов с часовым поясом UTC.

Если задано от одного до семи аргументов, они интерпретируются согласно первой приведённой выше последовательности вызова:

Time.utc(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0)

Примеры:

Time.utc(2000)  # => 2000-01-01 00:00:00 UTC
Time.utc(-2000) # => -2000-01-01 00:00:00 UTC

Для обязательного аргумента year минимальные и максимальные значения не заданы.

Необязательные аргументы:

month: месяц в диапазоне (1..12) или название месяца из трёх букв без учёта регистра:

Time.utc(2000, 1)     # => 2000-01-01 00:00:00 UTC
Time.utc(2000, 12)    # => 2000-12-01 00:00:00 UTC
Time.utc(2000, 'jan') # => 2000-01-01 00:00:00 UTC
Time.utc(2000, 'JAN') # => 2000-01-01 00:00:00 UTC

mday: день месяца в диапазоне (1..31):

Time.utc(2000, 1, 1)  # => 2000-01-01 00:00:00 UTC
Time.utc(2000, 1, 31) # => 2000-01-31 00:00:00 UTC

hour: час в диапазоне (0..23) или 24, если min, sec и usec равны нулю:

Time.utc(2000, 1, 1, 0)  # => 2000-01-01 00:00:00 UTC
Time.utc(2000, 1, 1, 23) # => 2000-01-01 23:00:00 UTC
Time.utc(2000, 1, 1, 24) # => 2000-01-02 00:00:00 UTC

min: минута в диапазоне (0..59):

Time.utc(2000, 1, 1, 0, 0)  # => 2000-01-01 00:00:00 UTC
Time.utc(2000, 1, 1, 0, 59) # => 2000-01-01 00:59:00 UTC

sec: секунда в диапазоне (0..59) или 60, если usec равен нулю:

Time.utc(2000, 1, 1, 0, 0, 0)  # => 2000-01-01 00:00:00 UTC
Time.utc(2000, 1, 1, 0, 0, 59) # => 2000-01-01 00:00:59 UTC
Time.utc(2000, 1, 1, 0, 0, 60) # => 2000-01-01 00:01:00 UTC

usec: микросекунда в диапазоне (0..999999):

Time.utc(2000, 1, 1, 0, 0, 0, 0)      # => 2000-01-01 00:00:00 UTC
Time.utc(2000, 1, 1, 0, 0, 0, 999999) # => 2000-01-01 00:00:00.999999 UTC

Значения могут быть представлены как:

Целые числа, как указано выше.

Числа, преобразуемые в целые:

Time.utc(Float(0.0), Rational(1, 1), 1.0, 0.0, 0.0, 0.0, 0.0)
# => 0000-01-01 00:00:00 UTC

Целые числа типа String:

a = %w[0 1 1 0 0 0 0 0]
# => ["0", "1", "1", "0", "0", "0", "0", "0"]
Time.utc(*a) # => 0000-01-01 00:00:00 UTC

Если задано ровно десять аргументов, они интерпретируются согласно второй приведённой выше последовательности вызова:

Time.utc(sec, min, hour, mday, month, year, dummy, dummy, dummy, dummy)

аргументы dummy игнорируются:

a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
# => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Time.utc(*a) # => 0005-04-03 02:01:00 UTC

Эта форма удобна для создания объекта Time из массива из 10 элементов, возвращённого методом Time.to_a:

t = Time.new(2000, 1, 2, 3, 4, 5, 6) # => 2000-01-02 03:04:05 +000006
a = t.to_a   # => [5, 4, 3, 2, 1, 2000, 0, 2, false, nil]
Time.utc(*a) # => 2000-01-02 03:04:05 UTC

Первые шесть аргументов обеих форм совпадают, хотя и следуют в разном порядке; диапазоны допустимых значений этих аргументов одинаковы для обеих форм (см. выше).

Возникает исключение, если количество аргументов равно восьми или девяти либо превышает десять.

Связанный метод: Time.local.

Также имеет псевдоним: gm

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

# File lib/time.rb, line 626
def xmlschema(time)
  if /\A\s*
      (-?\d+)-(\d\d)-(\d\d)
      T
      (\d\d):(\d\d):(\d\d)
      (\.\d+)?
      (Z|[+-]\d\d(?::?\d\d)?)?
      \s*\z/ix =~ time
    year = $1.to_i
    mon = $2.to_i
    day = $3.to_i
    hour = $4.to_i
    min = $5.to_i
    sec = $6.to_i
    usec = 0
    if $7
      usec = Rational($7) * 1000000
    end
    if $8
      zone = $8
      off = zone_offset(zone)
      year, mon, day, hour, min, sec =
        apply_offset(year, mon, day, hour, min, sec, off)
      t = self.utc(year, mon, day, hour, min, sec, usec)
      force_zone!(t, zone, off)
      t
    else
      self.local(year, mon, day, hour, min, sec, usec)
    end
  else
    raise ArgumentError.new("invalid xmlschema format: #{time.inspect}")
  end
end

Разбирает time как дату и время, определённые XML Schema, и преобразует их в объект Time. Формат представляет собой ограниченную версию формата, определённого ISO 8601.

Возникает исключение ArgumentError, если time не соответствует формату или если класс Time не может представить указанное время.

Дополнительные сведения об этом формате см. в разделе xmlschema.

require 'time'

Time.xmlschema("2011-10-05T22:26:12-04:00")
#=> 2011-10-05 22:26:12-04:00

Чтобы использовать этот метод, необходимо подключить библиотеку ‘time’.

Также имеет псевдоним: iso8601

zone_offset (zone, year=nil) Показать исходный код

# File lib/time.rb, line 83
def zone_offset(zone, year=nil)
  off = nil
  zone = zone.upcase
  if /\A([+-])(\d\d)(:?)(\d\d)(?:\3(\d\d))?\z/ =~ zone
    off = ($1 == '-' ? -1 : 1) * (($2.to_i * 60 + $4.to_i) * 60 + $5.to_i)
  elsif zone.match?(/\A[+-]\d\d\z/)
    off = zone.to_i * 3600
  elsif ZoneOffset.include?(zone)
    off = ZoneOffset[zone] * 3600
  else
    year ||= self.now.year
    if ((t = self.local(year, 1, 1)).zone.upcase == zone rescue false)
      off = t.utc_offset
    elsif ((t = self.local(year, 7, 1)).zone.upcase == zone rescue false)
      off = t.utc_offset
    end
  end
  off
end

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

Поддерживаются Numeric часовые пояса с минутами, например -10:00 или +1330, а также более простые часовые пояса, задаваемые только часами, например -10 или +13.

Также поддерживаются текстовые часовые пояса, перечисленные в ZoneOffset.

Если часовой пояс не соответствует ни одному из перечисленных выше, zone_offset проверит, совпадает ли местный часовой пояс (как с учётом возможного перехода на летнее время, так и без него) с zone. Если указать значение year, изменится год, используемый для определения местного часового пояса.

Если zone_offset не удастся определить смещение, будет возвращено nil.

require 'time'

Time.zone_offset("EST") #=> -18000

Чтобы использовать этот метод, необходимо подключить библиотеку ‘time’.

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

self + numeric → new_time Показать исходный код

static VALUE
time_plus(VALUE time1, VALUE time2)
{
    struct time_object *tobj;
    GetTimeval(time1, tobj);

    if (IsTimeval(time2)) {
        rb_raise(rb_eTypeError, "time + time?");
    }
    return time_add(tobj, time1, time2, 1);
}

Возвращает новый объект Time, значение которого равно сумме числового значения self и заданного numeric:

t = Time.new(2000) # => 2000-01-01 00:00:00 -0600
t + (60 * 60 * 24) # => 2000-01-02 00:00:00 -0600
t + 0.5            # => 2000-01-01 00:00:00.5 -0600

Связанный метод: Time#-.

self - numeric → new_time Показать исходный код

self - other_time → float

static VALUE
time_minus(VALUE time1, VALUE time2)
{
    struct time_object *tobj;

    GetTimeval(time1, tobj);
    if (IsTimeval(time2)) {
        struct time_object *tobj2;

        GetTimeval(time2, tobj2);
        return rb_Float(rb_time_unmagnify_to_float(wsub(tobj->timew, tobj2->timew)));
    }
    return time_add(tobj, time1, time2, -1);
}

Если задан numeric, возвращает новый объект Time, значение которого равно разности числовых значений self и numeric:

t = Time.new(2000) # => 2000-01-01 00:00:00 -0600
t - (60 * 60 * 24) # => 1999-12-31 00:00:00 -0600
t - 0.5            # => 1999-12-31 23:59:59.5 -0600

Если задан other_time, возвращает объект Float, значение которого равно разности числовых значений self и other_time в секундах:

t - t # => 0.0

Связанный метод: Time#+.

self <=> other_time → -1, 0, +1, or nil Показать исходный код

static VALUE
time_cmp(VALUE time1, VALUE time2)
{
    struct time_object *tobj1, *tobj2;
    int n;

    GetTimeval(time1, tobj1);
    if (IsTimeval(time2)) {
        GetTimeval(time2, tobj2);
        n = wcmp(tobj1->timew, tobj2->timew);
    }
    else {
        return rb_invcmp(time1, time2);
    }
    if (n == 0) return INT2FIX(0);
    if (n > 0) return INT2FIX(1);
    return INT2FIX(-1);
}

Сравнивает self с other_time; возвращает:

-1, если self меньше, чем other_time.
0, если self равно other_time.
1, если self больше, чем other_time.
nil, если self и other_time несравнимы.

Примеры:

t = Time.now     # => 2007-11-19 08:12:12 -0600
t2 = t + 2592000 # => 2007-12-19 08:12:12 -0600
t <=> t2         # => -1
t2 <=> t         # => 1

t = Time.now     # => 2007-11-19 08:13:38 -0600
t2 = t + 0.1     # => 2007-11-19 08:13:38 -0600
t.nsec           # => 98222999
t2.nsec          # => 198222999
t <=> t2         # => -1
t2 <=> t         # => 1
t <=> t          # => 0

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

# File ext/json/lib/json/add/time.rb, line 32
def as_json(*)
  {
    JSON.create_id => self.class.name,
    's'            => tv_sec,
    'n'            => tv_nsec,
  }
end

Методы Time#as_json и Time.json_create можно использовать для сериализации и десериализации объекта Time; см. Marshal.

Метод Time#as_json сериализует self и возвращает хеш из 2 элементов, представляющий self:

require 'json/add/time'
x = Time.now.as_json
# => {"json_class"=>"Time", "s"=>1700931656, "n"=>472846644}

Метод JSON.create десериализует такой хеш и возвращает объект Time:

Time.json_create(x)
# => 2023-11-25 11:00:56.472846644 -0600

asctime

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

ceil(ndigits = 0) → new_time Показать исходный код

static VALUE
time_ceil(int argc, VALUE *argv, VALUE time)
{
    VALUE ndigits, v, den;
    struct time_object *tobj;

    if (!rb_check_arity(argc, 0, 1) || NIL_P(ndigits = argv[0]))
        den = INT2FIX(1);
    else
        den = ndigits_denominator(ndigits);

    GetTimeval(time, tobj);
    v = w2v(rb_time_unmagnify(tobj->timew));

    v = modv(v, den);
    if (!rb_equal(v, INT2FIX(0))) {
        v = subv(den, v);
    }
    return time_add(tobj, time, v, 1);
}

Возвращает новый объект Time, числовое значение которого больше или равно self, с усечённым до точности ndigits значением секунд:

t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r)
t          # => 2010-03-30 05:43:25.123456789 UTC
t.ceil     # => 2010-03-30 05:43:26 UTC
t.ceil(2)  # => 2010-03-30 05:43:25.13 UTC
t.ceil(4)  # => 2010-03-30 05:43:25.1235 UTC
t.ceil(6)  # => 2010-03-30 05:43:25.123457 UTC
t.ceil(8)  # => 2010-03-30 05:43:25.12345679 UTC
t.ceil(10) # => 2010-03-30 05:43:25.123456789 UTC

t = Time.utc(1999, 12, 31, 23, 59, 59)
t              # => 1999-12-31 23:59:59 UTC
(t + 0.4).ceil # => 2000-01-01 00:00:00 UTC
(t + 0.9).ceil # => 2000-01-01 00:00:00 UTC
(t + 1.4).ceil # => 2000-01-01 00:00:01 UTC
(t + 1.9).ceil # => 2000-01-01 00:00:01 UTC

Связанные методы: Time#floor, Time#round.

ctime → string Показать исходный код

static VALUE
time_asctime(VALUE time)
{
    return strftimev("%a %b %e %T %Y", time, rb_usascii_encoding());
}

Возвращает строковое представление self, отформатированное с помощью strftime('%a %b %e %T %Y') или его сокращённой версии strftime('%c'); см. Форматы дат и времени:

t = Time.new(2000, 12, 31, 23, 59, 59, 0.5)
t.ctime                      # => "Sun Dec 31 23:59:59 2000"
t.strftime('%a %b %e %T %Y') # => "Sun Dec 31 23:59:59 2000"
t.strftime('%c')             # => "Sun Dec 31 23:59:59 2000"

Связанные методы: Time#to_s, Time#inspect:

t.inspect                    # => "2000-12-31 23:59:59.5 +000001"
t.to_s                       # => "2000-12-31 23:59:59 +0000"

Также имеет псевдоним: asctime

day

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

deconstruct_keys(array_of_names_or_nil) → hash Показать исходный код

static VALUE
time_deconstruct_keys(VALUE time, VALUE keys)
{
    struct time_object *tobj;
    VALUE h;
    long i;

    GetTimeval(time, tobj);
    MAKE_TM_ENSURE(time, tobj, tobj->vtm.yday != 0);

    if (NIL_P(keys)) {
        h = rb_hash_new_with_size(11);

        rb_hash_aset(h, sym_year, tobj->vtm.year);
        rb_hash_aset(h, sym_month, INT2FIX(tobj->vtm.mon));
        rb_hash_aset(h, sym_day, INT2FIX(tobj->vtm.mday));
        rb_hash_aset(h, sym_yday, INT2FIX(tobj->vtm.yday));
        rb_hash_aset(h, sym_wday, INT2FIX(tobj->vtm.wday));
        rb_hash_aset(h, sym_hour, INT2FIX(tobj->vtm.hour));
        rb_hash_aset(h, sym_min, INT2FIX(tobj->vtm.min));
        rb_hash_aset(h, sym_sec, INT2FIX(tobj->vtm.sec));
        rb_hash_aset(h, sym_subsec,
                     quov(w2v(wmod(tobj->timew, WINT2FIXWV(TIME_SCALE))), INT2FIX(TIME_SCALE)));
        rb_hash_aset(h, sym_dst, RBOOL(tobj->vtm.isdst));
        rb_hash_aset(h, sym_zone, time_zone(time));

        return h;
    }
    if (UNLIKELY(!RB_TYPE_P(keys, T_ARRAY))) {
        rb_raise(rb_eTypeError,
                 "wrong argument type %"PRIsVALUE" (expected Array or nil)",
                 rb_obj_class(keys));

    }

    h = rb_hash_new_with_size(RARRAY_LEN(keys));

    for (i=0; i<RARRAY_LEN(keys); i++) {
        VALUE key = RARRAY_AREF(keys, i);

        if (sym_year == key) rb_hash_aset(h, key, tobj->vtm.year);
        if (sym_month == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.mon));
        if (sym_day == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.mday));
        if (sym_yday == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.yday));
        if (sym_wday == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.wday));
        if (sym_hour == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.hour));
        if (sym_min == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.min));
        if (sym_sec == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.sec));
        if (sym_subsec == key) {
            rb_hash_aset(h, key, quov(w2v(wmod(tobj->timew, WINT2FIXWV(TIME_SCALE))), INT2FIX(TIME_SCALE)));
        }
        if (sym_dst == key) rb_hash_aset(h, key, RBOOL(tobj->vtm.isdst));
        if (sym_zone == key) rb_hash_aset(h, key, time_zone(time));
    }
    return h;
}

Возвращает хеш пар имя/значение для сопоставления с образцом. Возможные ключи: :year, :month, :day, :yday, :wday, :hour, :min, :sec, :subsec, :dst, :zone.

Возможные варианты использования:

t = Time.utc(2022, 10, 5, 21, 25, 30)

if t in wday: 3, day: ..7  # uses deconstruct_keys underneath
  puts "first Wednesday of the month"
end
#=> prints "first Wednesday of the month"

case t
in year: ...2022
  puts "too old"
in month: ..9
  puts "quarter 1-3"
in wday: 1..5, month:
  puts "working day in month #{month}"
end
#=> prints "working day in month 10"

Обратите внимание, что сопоставление с образцом также можно объединить с проверкой класса:

if t in Time(wday: 3, day: ..7)
  puts "first Wednesday of the month"
end

dst? → true or false

Возвращает true, если self находится в периоде летнего времени, и false в противном случае:

t = Time.local(2000, 1, 1) # => 2000-01-01 00:00:00 -0600
t.zone                     # => "Central Standard Time"
t.dst?                     # => false
t = Time.local(2000, 7, 1) # => 2000-07-01 00:00:00 -0500
t.zone                     # => "Central Daylight Time"
t.dst?                     # => true

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

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

static VALUE
time_eql(VALUE time1, VALUE time2)
{
    struct time_object *tobj1, *tobj2;

    GetTimeval(time1, tobj1);
    if (IsTimeval(time2)) {
        GetTimeval(time2, tobj2);
        return rb_equal(w2v(tobj1->timew), w2v(tobj2->timew));
    }
    return Qfalse;
}

Возвращает true, если self и other_time являются объектами Time с абсолютно одинаковым значением времени.

floor(ndigits = 0) → new_time Показать исходный код

static VALUE
time_floor(int argc, VALUE *argv, VALUE time)
{
    VALUE ndigits, v, den;
    struct time_object *tobj;

    if (!rb_check_arity(argc, 0, 1) || NIL_P(ndigits = argv[0]))
        den = INT2FIX(1);
    else
        den = ndigits_denominator(ndigits);

    GetTimeval(time, tobj);
    v = w2v(rb_time_unmagnify(tobj->timew));

    v = modv(v, den);
    return time_add(tobj, time, v, -1);
}

Возвращает новый объект Time, числовое значение которого меньше или равно self, с усечённым до точности ndigits значением секунд:

t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r)
t           # => 2010-03-30 05:43:25.123456789 UTC
t.floor     # => 2010-03-30 05:43:25 UTC
t.floor(2)  # => 2010-03-30 05:43:25.12 UTC
t.floor(4)  # => 2010-03-30 05:43:25.1234 UTC
t.floor(6)  # => 2010-03-30 05:43:25.123456 UTC
t.floor(8)  # => 2010-03-30 05:43:25.12345678 UTC
t.floor(10) # => 2010-03-30 05:43:25.123456789 UTC

t = Time.utc(1999, 12, 31, 23, 59, 59)
t               # => 1999-12-31 23:59:59 UTC
(t + 0.4).floor # => 1999-12-31 23:59:59 UTC
(t + 0.9).floor # => 1999-12-31 23:59:59 UTC
(t + 1.4).floor # => 2000-01-01 00:00:00 UTC
(t + 1.9).floor # => 2000-01-01 00:00:00 UTC

Связанные методы: Time#ceil, Time#round.

friday? → true or false Показать исходный код

static VALUE
time_friday(VALUE time)
{
    wday_p(5);
}

Возвращает true, если self соответствует пятнице, и false в противном случае:

t = Time.utc(2000, 1, 7) # => 2000-01-07 00:00:00 UTC
t.friday?                # => true

Связанные методы: Time#saturday?, Time#sunday?, Time#monday?.

getgm Показать исходный код

static VALUE
time_getgmtime(VALUE time)
{
    return time_gmtime(time_dup(time));
}

Также имеет псевдоним: getutc

getlocal(zone = nil) → new_time Показать исходный код

static VALUE
time_getlocaltime(int argc, VALUE *argv, VALUE time)
{
    VALUE off;

    if (rb_check_arity(argc, 0, 1) && !NIL_P(off = argv[0])) {
        VALUE zone = off;
        if (maybe_tzobj_p(zone)) {
            VALUE t = time_dup(time);
            if (zone_localtime(off, t)) return t;
        }

        if (NIL_P(off = utc_offset_arg(off))) {
            off = zone;
            if (NIL_P(zone = find_timezone(time, off))) invalid_utc_offset(off);
            time = time_dup(time);
            if (!zone_localtime(zone, time)) invalid_utc_offset(off);
            return time;
        }
        else if (off == UTC_ZONE) {
            return time_gmtime(time_dup(time));
        }
        validate_utc_offset(off);

        time = time_dup(time);
        time_set_utc_offset(time, off);
        return time_fixoff(time);
    }

    return time_localtime(time_dup(time));
}

Возвращает новый объект Time, представляющий значение self, преобразованное в заданный часовой пояс; если zone равен nil, используется местный часовой пояс:

t = Time.utc(2000)                    # => 2000-01-01 00:00:00 UTC
t.getlocal                            # => 1999-12-31 18:00:00 -0600
t.getlocal('+12:00')                  # => 2000-01-01 12:00:00 +1200

Варианты аргумента zone см. в разделе Обозначения часовых поясов.

getutc → new_time

Возвращает новый объект Time, представляющий значение self, преобразованное в часовой пояс UTC:

local = Time.local(2000) # => 2000-01-01 00:00:00 -0600
local.utc?               # => false
utc = local.getutc       # => 2000-01-01 06:00:00 UTC
utc.utc?                 # => true
utc == local             # => true

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

gmt?

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

gmt_offset

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

gmtime Показать исходный код

static VALUE
time_gmtime(VALUE time)
{
    struct time_object *tobj;
    struct vtm vtm;

    GetTimeval(time, tobj);
    if (TZMODE_UTC_P(tobj)) {
        if (tobj->vtm.tm_got)
            return time;
    }
    else {
        time_modify(time);
    }

    vtm.zone = str_utc;
    GMTIMEW(tobj->timew, &vtm);
    time_set_vtm(time, tobj, vtm);

    tobj->vtm.tm_got = 1;
    TZMODE_SET_UTC(tobj);
    return time;
}

Также имеет псевдоним: utc

gmtoff Показать исходный код

VALUE
rb_time_utc_offset(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);

    if (TZMODE_UTC_P(tobj)) {
        return INT2FIX(0);
    }
    else {
        MAKE_TM(time, tobj);
        return tobj->vtm.utc_offset;
    }
}

Также имеет псевдонимы: gmt_offset, utc_offset

hash → integer Показать исходный код

static VALUE
time_hash(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    return rb_hash(w2v(tobj->timew));
}

Возвращает целочисленный хеш-код для self.

Связанный метод: Object#hash.

hour → integer Показать исходный код

static VALUE
time_hour(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    return INT2FIX(tobj->vtm.hour);
}

Возвращает целочисленное значение часа дня для self в диапазоне (0..23):

t = Time.new(2000, 1, 2, 3, 4, 5, 6)
# => 2000-01-02 03:04:05 +000006
t.hour # => 3

Связанные методы: Time#year, Time#mon, Time#min.

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

# File lib/time.rb, line 698
def httpdate
  getutc.strftime('%a, %d %b %Y %T GMT')
end

Возвращает строку, представляющую время в формате даты RFC 1123, или HTTP-date, определённом RFC 2616:

day-of-week, DD month-name CCYY hh:mm:ss GMT

Обратите внимание, что результат всегда представлен в UTC (GMT).

require 'time'

t = Time.now
t.httpdate # => "Thu, 06 Oct 2011 02:26:12 GMT"

Для использования этого метода необходимо подключить библиотеку ‘time’.

inspect → string Показать исходный код

static VALUE
time_inspect(VALUE time)
{
    struct time_object *tobj;
    VALUE str, subsec;

    GetTimeval(time, tobj);
    str = strftimev("%Y-%m-%d %H:%M:%S", time, rb_usascii_encoding());
    subsec = w2v(wmod(tobj->timew, WINT2FIXWV(TIME_SCALE)));
    if (subsec == INT2FIX(0)) {
    }
    else if (FIXNUM_P(subsec) && FIX2LONG(subsec) < TIME_SCALE) {
        long len;
        rb_str_catf(str, ".%09ld", FIX2LONG(subsec));
        for (len=RSTRING_LEN(str); RSTRING_PTR(str)[len-1] == '0' && len > 0; len--)
            ;
        rb_str_resize(str, len);
    }
    else {
        rb_str_cat_cstr(str, " ");
        subsec = quov(subsec, INT2FIX(TIME_SCALE));
        rb_str_concat(str, rb_obj_as_string(subsec));
    }
    if (TZMODE_UTC_P(tobj)) {
        rb_str_cat_cstr(str, " UTC");
    }
    else {
        /* ?TODO: subsecond offset */
        long off = NUM2LONG(rb_funcall(tobj->vtm.utc_offset, rb_intern("round"), 0));
        char sign = (off < 0) ? (off = -off, '-') : '+';
        int sec = off % 60;
        int min = (off /= 60) % 60;
        off /= 60;
        rb_str_catf(str, " %c%.2d%.2d", sign, (int)off, min);
        if (sec) rb_str_catf(str, "%.2d", sec);
    }
    return str;
}

Возвращает строковое представление self с долями секунды:

t = Time.new(2000, 12, 31, 23, 59, 59, 0.5)
t.inspect # => "2000-12-31 23:59:59.5 +000001"

Связанные методы: Time#ctime, Time#to_s:

t.ctime   # => "Sun Dec 31 23:59:59 2000"
t.to_s    # => "2000-12-31 23:59:59 +0000"

isdst Показать исходный код

static VALUE
time_isdst(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    if (tobj->vtm.isdst == VTM_ISDST_INITVAL) {
        rb_raise(rb_eRuntimeError, "isdst is not set yet");
    }
    return RBOOL(tobj->vtm.isdst);
}

Также имеет псевдоним: dst?

iso8601 (fraction_digits=0)

Вызывается исключение ArgumentError, если time не соответствует формату или если класс Time не может представить указанное время.

Дополнительную информацию об этом формате см. в описании xmlschema.

require 'time'

Time.xmlschema("2011-10-05T22:26:12-04:00")
#=> 2011-10-05 22:26:12-04:00

Для использования этого метода необходимо подключить библиотеку ‘time’.

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

localtime → self or new_time Показать исходный код

localtime(zone) → new_time

static VALUE
time_localtime_m(int argc, VALUE *argv, VALUE time)
{
    VALUE off;

    if (rb_check_arity(argc, 0, 1) && !NIL_P(off = argv[0])) {
        return time_zonelocal(time, off);
    }

    return time_localtime(time);
}

Если аргумент не задан:

Возвращает self, если self является местным временем.
В противном случае возвращает новый объект Time в местном часовом поясе пользователя:
```
t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
t.localtime                         # => 2000-01-01 14:15:01 -0600
```

Если задан аргумент zone, возвращает новый объект Time, созданный преобразованием self в заданный часовой пояс:

t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
t.localtime("-09:00")               # => 2000-01-01 11:15:01 -0900

Варианты аргумента zone см. в разделе Обозначения часовых поясов.

mday → integer Показать исходный код

static VALUE
time_mday(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    return INT2FIX(tobj->vtm.mday);
}

Возвращает целочисленный день месяца для self в диапазоне (1..31):

t = Time.new(2000, 1, 2, 3, 4, 5, 6)
# => 2000-01-02 03:04:05 +000006
t.mday # => 2

Связанные методы: Time#year, Time#hour, Time#min.

Также имеет псевдоним: day

min → integer Показать исходный код

static VALUE
time_min(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    return INT2FIX(tobj->vtm.min);
}

Возвращает целочисленное значение минуты часа для self в диапазоне (0..59):

t = Time.new(2000, 1, 2, 3, 4, 5, 6)
# => 2000-01-02 03:04:05 +000006
t.min # => 4

Связанные методы: Time#year, Time#mon, Time#sec.

mon → integer Показать исходный код

static VALUE
time_mon(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    return INT2FIX(tobj->vtm.mon);
}

Возвращает целочисленный месяц года для self в диапазоне (1..12):

t = Time.new(2000, 1, 2, 3, 4, 5, 6)
# => 2000-01-02 03:04:05 +000006
t.mon # => 1

Связанные методы: Time#year, Time#hour, Time#min.

Также имеет псевдоним: month

monday? → true or false Показать исходный код

static VALUE
time_monday(VALUE time)
{
    wday_p(1);
}

Возвращает true, если self соответствует понедельнику, и false в противном случае:

t = Time.utc(2000, 1, 3) # => 2000-01-03 00:00:00 UTC
t.monday?                # => true

Связанные методы: Time#tuesday?, Time#wednesday?, Time#thursday?.

month

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

nsec → integer

Возвращает количество наносекунд в дробной части секунд self в диапазоне (0..999_999_999); младшие разряды отсекаются, а не округляются:

t = Time.now # => 2022-07-11 15:04:53.3219637 -0500
t.nsec       # => 321963700

Связанный метод: Time#subsec (возвращает точную дробную часть секунды).

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

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

# File lib/time.rb, line 678
def rfc2822
  strftime('%a, %d %b %Y %T ') << (utc? ? '-0000' : strftime('%z'))
end

Возвращает строку, представляющую время в формате даты и времени, определённом RFC 2822:

day-of-week, DD month-name CCYY hh:mm:ss zone

где zone — это [+-]hhmm.

Если self представляет время UTC, в качестве часового пояса используется -0000.

require 'time'

t = Time.now
t.rfc2822  # => "Wed, 05 Oct 2011 22:26:12 -0400"

Для использования этого метода необходимо подключить библиотеку ‘time’.

Также имеет псевдоним: rfc822

rfc822 ()

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

round(ndigits = 0) → new_time Показать исходный код

static VALUE
time_round(int argc, VALUE *argv, VALUE time)
{
    VALUE ndigits, v, den;
    struct time_object *tobj;

    if (!rb_check_arity(argc, 0, 1) || NIL_P(ndigits = argv[0]))
        den = INT2FIX(1);
    else
        den = ndigits_denominator(ndigits);

    GetTimeval(time, tobj);
    v = w2v(rb_time_unmagnify(tobj->timew));

    v = modv(v, den);
    if (lt(v, quov(den, INT2FIX(2))))
        return time_add(tobj, time, v, -1);
    else
        return time_add(tobj, time, subv(den, v), 1);
}

Возвращает новый объект Time, числовое значение которого равно значению self, а значение секунд округлено до точности ndigits:

t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r)
t          # => 2010-03-30 05:43:25.123456789 UTC
t.round    # => 2010-03-30 05:43:25 UTC
t.round(0) # => 2010-03-30 05:43:25 UTC
t.round(1) # => 2010-03-30 05:43:25.1 UTC
t.round(2) # => 2010-03-30 05:43:25.12 UTC
t.round(3) # => 2010-03-30 05:43:25.123 UTC
t.round(4) # => 2010-03-30 05:43:25.1235 UTC

t = Time.utc(1999, 12,31, 23, 59, 59)
t                # => 1999-12-31 23:59:59 UTC
(t + 0.4).round  # => 1999-12-31 23:59:59 UTC
(t + 0.49).round # => 1999-12-31 23:59:59 UTC
(t + 0.5).round  # => 2000-01-01 00:00:00 UTC
(t + 1.4).round  # => 2000-01-01 00:00:00 UTC
(t + 1.49).round # => 2000-01-01 00:00:00 UTC
(t + 1.5).round  # => 2000-01-01 00:00:01 UTC

Связанные методы: Time#ceil, Time#floor.

saturday? → true or false Показать исходный код

static VALUE
time_saturday(VALUE time)
{
    wday_p(6);
}

Возвращает true, если self соответствует субботе, и false в противном случае:

t = Time.utc(2000, 1, 1) # => 2000-01-01 00:00:00 UTC
t.saturday?              # => true

Связанные методы: Time#sunday?, Time#monday?, Time#tuesday?.

sec → integer Показать исходный код

static VALUE
time_sec(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    return INT2FIX(tobj->vtm.sec);
}

Возвращает целочисленное значение секунды минуты для self в диапазоне (0..60):

t = Time.new(2000, 1, 2, 3, 4, 5, 6)
# => 2000-01-02 03:04:05 +000006
t.sec # => 5

Примечание: значение секунд может быть равно 60 при наличии високосной секунды.

Связанные методы: Time#year, Time#mon, Time#min.

strftime(format_string) → string Показать исходный код

static VALUE
time_strftime(VALUE time, VALUE format)
{
    struct time_object *tobj;
    const char *fmt;
    long len;
    rb_encoding *enc;
    VALUE tmp;

    GetTimeval(time, tobj);
    MAKE_TM_ENSURE(time, tobj, tobj->vtm.yday != 0);
    StringValue(format);
    if (!rb_enc_str_asciicompat_p(format)) {
        rb_raise(rb_eArgError, "format should have ASCII compatible encoding");
    }
    tmp = rb_str_tmp_frozen_acquire(format);
    fmt = RSTRING_PTR(tmp);
    len = RSTRING_LEN(tmp);
    enc = rb_enc_get(format);
    if (len == 0) {
        rb_warning("strftime called with empty format string");
        return rb_enc_str_new(0, 0, enc);
    }
    else {
        VALUE str = rb_strftime_alloc(fmt, len, enc, time, &tobj->vtm, tobj->timew,
                                      TZMODE_UTC_P(tobj));
        rb_str_tmp_frozen_release(format, tmp);
        if (!str) rb_raise(rb_eArgError, "invalid format: %"PRIsVALUE, format);
        return str;
    }
}

Возвращает строковое представление self, отформатированное в соответствии с заданной строкой format. См. Форматы дат и времени.

subsec → numeric Показать исходный код

static VALUE
time_subsec(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    return quov(w2v(wmod(tobj->timew, WINT2FIXWV(TIME_SCALE))), INT2FIX(TIME_SCALE));
}

Возвращает точное значение дробной части секунды для self в виде Numeric (Integer или Rational):

t = Time.now # => 2022-07-11 15:11:36.8490302 -0500
t.subsec     # => (4245151/5000000)

Если дробная часть секунды равна нулю, возвращается целочисленный ноль:

t = Time.new(2000, 1, 1, 2, 3, 4) # => 2000-01-01 02:03:04 -0600
t.subsec                          # => 0

sunday? → true or false Показать исходный код

static VALUE
time_sunday(VALUE time)
{
    wday_p(0);
}

Возвращает true, если self соответствует воскресенью, и false в противном случае:

t = Time.utc(2000, 1, 2) # => 2000-01-02 00:00:00 UTC
t.sunday?                # => true

Связанные методы: Time#monday?, Time#tuesday?, Time#wednesday?.

thursday? → true or false Показать исходный код

static VALUE
time_thursday(VALUE time)
{
    wday_p(4);
}

Возвращает true, если self соответствует четвергу, и false в противном случае:

t = Time.utc(2000, 1, 6) # => 2000-01-06 00:00:00 UTC
t.thursday?              # => true

Связанные методы: Time#friday?, Time#saturday?, Time#sunday?.

to_a → array Показать исходный код

static VALUE
time_to_a(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM_ENSURE(time, tobj, tobj->vtm.yday != 0);
    return rb_ary_new3(10,
                    INT2FIX(tobj->vtm.sec),
                    INT2FIX(tobj->vtm.min),
                    INT2FIX(tobj->vtm.hour),
                    INT2FIX(tobj->vtm.mday),
                    INT2FIX(tobj->vtm.mon),
                    tobj->vtm.year,
                    INT2FIX(tobj->vtm.wday),
                    INT2FIX(tobj->vtm.yday),
                    RBOOL(tobj->vtm.isdst),
                    time_zone(time));
}

Возвращает массив из 10 значений, представляющих self:

Time.utc(2000, 1, 1).to_a
# => [0,   0,   0,    1,   1,   2000, 6,    1,    false, "UTC"]
#    [sec, min, hour, day, mon, year, wday, yday, dst?,   zone]

Возвращённый массив можно использовать в качестве аргумента для Time.utc или Time.local, чтобы создать новый объект Time.

to_date → date Показать исходный код

static VALUE
time_to_date(VALUE self)
{
    VALUE y, nth, ret;
    int ry, m, d;

    y = f_year(self);
    m = FIX2INT(f_mon(self));
    d = FIX2INT(f_mday(self));

    decode_year(y, -1, &nth, &ry);

    ret = d_simple_new_internal(cDate,
                                nth, 0,
                                GREGORIAN,
                                ry, m, d,
                                HAVE_CIVIL);
    {
        get_d1(ret);
        set_sg(dat, DEFAULT_SG);
    }
    return ret;
}

Возвращает объект Date, обозначающий self.

to_datetime → datetime Показать исходный код

static VALUE
time_to_datetime(VALUE self)
{
    VALUE y, sf, nth, ret;
    int ry, m, d, h, min, s, of;

    y = f_year(self);
    m = FIX2INT(f_mon(self));
    d = FIX2INT(f_mday(self));

    h = FIX2INT(f_hour(self));
    min = FIX2INT(f_min(self));
    s = FIX2INT(f_sec(self));
    if (s == 60)
        s = 59;

    sf = sec_to_ns(f_subsec(self));
    of = FIX2INT(f_utc_offset(self));

    decode_year(y, -1, &nth, &ry);

    ret = d_complex_new_internal(cDateTime,
                                 nth, 0,
                                 0, sf,
                                 of, GREGORIAN,
                                 ry, m, d,
                                 h, min, s,
                                 HAVE_CIVIL | HAVE_TIME);
    {
        get_d1(ret);
        set_sg(dat, DEFAULT_SG);
    }
    return ret;
}

Возвращает объект DateTime, обозначающий self.

to_f → float Показать исходный код

static VALUE
time_to_f(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    return rb_Float(rb_time_unmagnify_to_float(tobj->timew));
}

Возвращает значение self в виде числа Float — секунд эпохи; дробные секунды включены.

Сохранённое значение self является числом Rational, поэтому возвращаемое значение может быть приближённым:

Time.utc(1970, 1, 1, 0, 0, 0).to_f         # => 0.0
Time.utc(1970, 1, 1, 0, 0, 0, 999999).to_f # => 0.999999
Time.utc(1950, 1, 1, 0, 0, 0).to_f         # => -631152000.0
Time.utc(1990, 1, 1, 0, 0, 0).to_f         # => 631152000.0

Связанные методы: Time#to_i, Time#to_r.

to_i → integer Показать исходный код

static VALUE
time_to_i(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    return w2v(wdiv(tobj->timew, WINT2FIXWV(TIME_SCALE)));
}

Возвращает значение self как целое число — секунды эпохи; дробные секунды отбрасываются (не округляются):

Time.utc(1970, 1, 1, 0, 0, 0).to_i         # => 0
Time.utc(1970, 1, 1, 0, 0, 0, 999999).to_i # => 0
Time.utc(1950, 1, 1, 0, 0, 0).to_i         # => -631152000
Time.utc(1990, 1, 1, 0, 0, 0).to_i         # => 631152000

Связанные методы: Time#to_f Time#to_r.

Также имеет псевдоним: tv_sec

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

# File ext/json/lib/json/add/time.rb, line 49
def to_json(*args)
  as_json.to_json(*args)
end

Возвращает строку JSON, представляющую self:

require 'json/add/time'
puts Time.now.to_json

Результат:

{"json_class":"Time","s":1700931678,"n":980650786}

to_r → rational Показать исходный код

static VALUE
time_to_r(VALUE time)
{
    struct time_object *tobj;
    VALUE v;

    GetTimeval(time, tobj);
    v = rb_time_unmagnify_to_rational(tobj->timew);
    if (!RB_TYPE_P(v, T_RATIONAL)) {
        v = rb_Rational1(v);
    }
    return v;
}

Возвращает значение self в виде точного числа Rational, выражающего секунды эпохи;

Time.now.to_r # => (16571402750320203/10000000)

Связанные методы: Time#to_f, Time#to_i.

to_s → string Показать исходный код

static VALUE
time_to_s(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    if (TZMODE_UTC_P(tobj))
        return strftimev("%Y-%m-%d %H:%M:%S UTC", time, rb_usascii_encoding());
    else
        return strftimev("%Y-%m-%d %H:%M:%S %z", time, rb_usascii_encoding());
}

Возвращает строковое представление self без дробных секунд:

t = Time.new(2000, 12, 31, 23, 59, 59, 0.5)
t.to_s    # => "2000-12-31 23:59:59 +0000"

Связанные методы: Time#ctime, Time#inspect:

t.ctime   # => "Sun Dec 31 23:59:59 2000"
t.inspect # => "2000-12-31 23:59:59.5 +000001"

to_time → time Показать исходный код

static VALUE
time_to_time(VALUE self)
{
    return self;
}

Возвращает self.

tuesday? → true or false Показать исходный код

static VALUE
time_tuesday(VALUE time)
{
    wday_p(2);
}

Возвращает true, если self обозначает вторник, и false в противном случае:

t = Time.utc(2000, 1, 4) # => 2000-01-04 00:00:00 UTC
t.tuesday?               # => true

Связанные методы: Time#wednesday?, Time#thursday?, Time#friday?.

tv_nsec Показать исходный код

static VALUE
time_nsec(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    return rb_to_int(w2v(wmulquoll(wmod(tobj->timew, WINT2WV(TIME_SCALE)), 1000000000, TIME_SCALE)));
}

Также имеет псевдоним: nsec

tv_sec

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

tv_usec Показать исходный код

static VALUE
time_usec(VALUE time)
{
    struct time_object *tobj;
    wideval_t w, q, r;

    GetTimeval(time, tobj);

    w = wmod(tobj->timew, WINT2WV(TIME_SCALE));
    wmuldivmod(w, WINT2FIXWV(1000000), WINT2FIXWV(TIME_SCALE), &q, &r);
    return rb_to_int(w2v(q));
}

Также имеет псевдоним: usec

usec → integer

Возвращает количество микросекунд в дробной части self в диапазоне (0..999_999); младшие разряды отбрасываются, а не округляются:

t = Time.now # => 2022-07-11 14:59:47.5484697 -0500
t.usec       # => 548469

Связанный метод: Time#subsec (возвращает точное значение дробных секунд).

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

utc → self

Возвращает self, преобразованный в часовой пояс UTC:

t = Time.new(2000) # => 2000-01-01 00:00:00 -0600
t.utc?             # => false
t.utc              # => 2000-01-01 06:00:00 UTC
t.utc?             # => true

Связанный метод: Time#getutc (возвращает новый преобразованный объект Time).

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

utc? → true or false Показать исходный код

static VALUE
time_utc_p(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    return RBOOL(TZMODE_UTC_P(tobj));
}

Возвращает true, если self обозначает время в UTC (GMT):

now = Time.now
# => 2022-08-18 10:24:13.5398485 -0500
now.utc? # => false
now.getutc.utc? # => true
utc = Time.utc(2000, 1, 1, 20, 15, 1)
# => 2000-01-01 20:15:01 UTC
utc.utc? # => true

Объекты Time, созданные следующими методами, считаются относящимися к UTC:

Объекты, созданные другими способами, не будут считаться относящимися к UTC, даже если значение переменной среды «TZ» равно «UTC».

Связанный метод: Time.utc.

Также имеет псевдоним: gmt?

utc_offset → integer

Возвращает разницу в секундах между часовыми поясами UTC и self:

Time.utc(2000, 1, 1).utc_offset   # => 0
Time.local(2000, 1, 1).utc_offset # => -21600 # -6*3600, or minus six hours.

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

wday → integer Показать исходный код

static VALUE
time_wday(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM_ENSURE(time, tobj, tobj->vtm.wday != VTM_WDAY_INITVAL);
    return INT2FIX((int)tobj->vtm.wday);
}

Возвращает целочисленный день недели для self в диапазоне (0..6), где воскресенье обозначается нулём.

t = Time.new(2000, 1, 2, 3, 4, 5, 6)
# => 2000-01-02 03:04:05 +000006
t.wday    # => 0
t.sunday? # => true

Связанные методы: Time#year, Time#hour, Time#min.

wednesday? → true or false Показать исходный код

static VALUE
time_wednesday(VALUE time)
{
    wday_p(3);
}

Возвращает true, если self обозначает среду, и false в противном случае:

t = Time.utc(2000, 1, 5) # => 2000-01-05 00:00:00 UTC
t.wednesday?             # => true

Связанные методы: Time#thursday?, Time#friday?, Time#saturday?.

xmlschema (fraction_digits=0) Показать исходный код

# File lib/time.rb, line 724
def xmlschema(fraction_digits=0)
  fraction_digits = fraction_digits.to_i
  s = strftime("%FT%T")
  if fraction_digits > 0
    s << strftime(".%#{fraction_digits}N")
  end
  s << (utc? ? 'Z' : strftime("%:z"))
end

Возвращает строку, представляющую время в виде dateTime, определённого XML Schema:

CCYY-MM-DDThh:mm:ssTZD
CCYY-MM-DDThh:mm:ss.sssTZD

где TZD — это Z или [+-]hh:mm.

Если self — время UTC, в качестве TZD используется Z. В противном случае используется [+-]hh:mm.

fraction_digits задаёт количество цифр для дробных секунд. Значение по умолчанию — 0.

require 'time'

t = Time.now
t.iso8601  # => "2011-10-05T22:26:12-04:00"

Чтобы использовать этот метод, необходимо подключить библиотеку ‘time’.

Также имеет псевдонимы: iso8601, iso8601

yday → integer Показать исходный код

static VALUE
time_yday(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM_ENSURE(time, tobj, tobj->vtm.yday != 0);
    return INT2FIX(tobj->vtm.yday);
}

Возвращает целочисленный день года для self в диапазоне (1..366).

Time.new(2000, 1, 1).yday   # => 1
Time.new(2000, 12, 31).yday # => 366

year → integer Показать исходный код

static VALUE
time_year(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    return tobj->vtm.year;
}

Возвращает год для self в виде целого числа:

t = Time.new(2000, 1, 2, 3, 4, 5, 6)
# => 2000-01-02 03:04:05 +000006
t.year # => 2000

Связанные методы: Time#mon, Time#hour, Time#min.

zone → string or timezone Показать исходный код

static VALUE
time_zone(VALUE time)
{
    struct time_object *tobj;
    VALUE zone;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);

    if (TZMODE_UTC_P(tobj)) {
        return rb_usascii_str_new_cstr("UTC");
    }
    zone = tobj->vtm.zone;
    if (NIL_P(zone))
        return Qnil;

    if (RB_TYPE_P(zone, T_STRING))
        zone = rb_str_dup(zone);
    return zone;
}

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

Time.utc(2000, 1, 1).zone # => "UTC"
Time.new(2000, 1, 1).zone # => "Central Standard Time"

Ruby Core © 1993–2025 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.

класс Time

Объекты типа Time

Объекты типа `Time`