Class: Time

Inherits:
Object
  • Object
show all
Defined in:
cybertrain/clock.rb,
cybertrain/time_ext.rb,
cybertrain/zoned_time.rb,
cybertrain/test/time_now.rb

Overview

Spec section 2.4, spike item 1 (PASS): in a test program, Time.now answers Cybertrain::Clock.now, so during a travel Time.now, and every framework or library call that reads it, follows the clock, as in Rails. Only test programs require this file; a production binary keeps the builtin. Cybertrain::Clock reads real time through Process.clock_gettime, never Time.now, so this cannot recurse. Time.new with no argument stays the builtin’s real time. Like the builtin, it answers local time (the process’s TZ): the clock’s instant through getlocal, which keeps the instant and the sub-second part and compiles under Spinel 2026.11.04.7026 (the offset and utc? match CRuby’s under TZ=UTC, Asia/Tokyo and America/New_York). Time.current stays UTC.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.current ⇒ Time

The current time on Cybertrain::Clock: a UTC Time (Rails answers a TimeWithZone). Follows travel_to in tests.

Returns:



166
# File 'cybertrain/clock.rb', line 166

def self.current = Cybertrain::Clock.now

.find_zone!(name) ⇒ Cybertrain::TimeZone

The zone named name (an IANA name such as “Asia/Tokyo”), as Rails’ Time.find_zone!, from the system zoneinfo (Cybertrain::TimeZone.find).

Parameters:

  • name (String)

Returns:

Raises:

  • (ArgumentError) —

    unknown time zone "Mars/Base" for a name the system zoneinfo does not have



117
118
119
120
121
122
123
124
125
# File 'cybertrain/zoned_time.rb', line 117

def self.find_zone!(name)
  key = name.to_s
  zone = Cybertrain::TimeZone.find(key)
  unless zone.found?
    msg = "unknown time zone #{key.inspect}"
    raise ArgumentError, msg
  end
  zone
end

.iso8601(text) ⇒ Time

The Time of an ISO 8601 string (T or a space, a fraction, Z or an offset), as Cybertrain::Cast.parse_time reads it.

Parameters:

  • text (String)

Returns:

Raises:

  • (ArgumentError) —

    “invalid date: …” when the text is not ISO 8601



20
21
22
23
24
# File 'cybertrain/time_ext.rb', line 20

def self.iso8601(text)
  time = Cybertrain::Cast.parse_time(text)
  raise ArgumentError, "invalid date: #{text}" if time.nil?
  time
end

.now ⇒ Time

Returns Cybertrain::Clock.now in local time, as the builtin Time.now answers.

Returns:



18
# File 'cybertrain/test/time_now.rb', line 18

def self.now = Cybertrain::Clock.now.getlocal

.rfc2822(text) ⇒ Time

The Time of an RFC 2822 string (Thu, 05 Nov 2026 09:00:00 +0000).

Parameters:

  • text (String)

Returns:

Raises:

  • (ArgumentError) —

    “invalid date: …” when the text is not RFC 2822



31
32
33
34
35
# File 'cybertrain/time_ext.rb', line 31

def self.rfc2822(text)
  time = Cybertrain::Cast.parse_time(text)
  raise ArgumentError, "invalid date: #{text}" if time.nil?
  time
end

.strptime(text, format) ⇒ Time

Parses text by format. Directives: %Y %m %d %H %M %S (%m and %d take one or two digits), %L (milliseconds), %z (Z, +HH, +HHMM, +HH:MM), %Z (UTC, GMT, Z), %b %B %a %A (English names, any case, abbreviated or full), %j (day of year), %s (epoch seconds) and %%; any other byte matches itself. Fields the format leaves out are 1970-01-01 00:00:00; the result is UTC.

Examples:

Time.strptime("05/10/2026 09:07", "%d/%m/%Y %H:%M") # => 2026-10-05 09:07:00 UTC

Parameters:

  • text (String)
  • format (String)

Returns:

Raises:

  • (ArgumentError) —

    “invalid date: …” when the text does not fit, “unsupported strptime directive %q” for a directive not listed



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
# File 'cybertrain/time_ext.rb', line 51

def self.strptime(text, format)
  s = text.to_s # NOTES rule 62: plain byte reads
  f = format.to_s
  n = s.bytesize
  fn = f.bytesize
  year = 1970
  month = 1
  day = 1
  hour = 0
  minute = 0
  second = 0
  usec = 0
  offset = 0
  yday = 0
  epoch = 0
  has_epoch = false
  i = 0
  j = 0
  while j < fn
    c = f.getbyte(j)
    j += 1
    if c != 37
      raise ArgumentError, "invalid date: #{text}" if i >= n || s.getbyte(i) != c
      i += 1
      next
    end
    raise ArgumentError, "unsupported strptime directive %" if j >= fn
    d = f.byteslice(j, 1)
    j += 1
    if d == "%"
      raise ArgumentError, "invalid date: #{text}" if i >= n || s.getbyte(i) != 37
      i += 1
    elsif d == "Y"
      len = strptime_digits(s, i, 4)
      raise ArgumentError, "invalid date: #{text}" if len < 4
      year = Cybertrain::Cast.number_at(s, i, len)
      i += len
    elsif d == "m" || d == "d" || d == "H" || d == "M" || d == "S"
      len = strptime_digits(s, i, 2)
      # %H, %M and %S want two digits; %m and %d accept one.
      min = (d == "m" || d == "d") ? 1 : 2
      raise ArgumentError, "invalid date: #{text}" if len < min
      v = Cybertrain::Cast.number_at(s, i, len)
      i += len
      if d == "m"
        month = v
      elsif d == "d"
        day = v
      elsif d == "H"
        hour = v
      elsif d == "M"
        minute = v
      else
        second = v
      end
    elsif d == "L"
      len = strptime_digits(s, i, 3)
      raise ArgumentError, "invalid date: #{text}" if len == 0
      usec = Cybertrain::Cast.number_at(s, i, len) * STRPTIME_MS_SCALE[len] * 1000
      i += len
    elsif d == "j"
      len = strptime_digits(s, i, 3)
      raise ArgumentError, "invalid date: #{text}" if len == 0
      yday = Cybertrain::Cast.number_at(s, i, len)
      raise ArgumentError, "invalid date: #{text}" if yday < 1 || yday > 366
      i += len
    elsif d == "s"
      neg = i < n && s.getbyte(i) == 45
      i += 1 if neg
      len = strptime_digits(s, i, 18)
      raise ArgumentError, "invalid date: #{text}" if len == 0
      epoch = Cybertrain::Cast.number_at(s, i, len)
      epoch = -epoch if neg
      has_epoch = true
      i += len
    elsif d == "b" || d == "B"
      idx = strptime_name(s, i, STRPTIME_MONTHS)
      raise ArgumentError, "invalid date: #{text}" if idx < 0
      month = idx + 1
      i += strptime_name_length(s, i, STRPTIME_MONTHS[idx])
    elsif d == "a" || d == "A"
      idx = strptime_name(s, i, STRPTIME_DAYS)
      raise ArgumentError, "invalid date: #{text}" if idx < 0
      i += strptime_name_length(s, i, STRPTIME_DAYS[idx])
    elsif d == "Z"
      w = strptime_word(s, i)
      zone = s.byteslice(i, w).downcase
      raise ArgumentError, "invalid date: #{text}" unless zone == "utc" || zone == "gmt" || zone == "z"
      i += w
    elsif d == "z"
      sign = i < n ? s.getbyte(i) : 0
      if sign == 90 || sign == 122
        i += 1
      else
        raise ArgumentError, "invalid date: #{text}" unless sign == 43 || sign == 45
        i += 1
        raise ArgumentError, "invalid date: #{text}" if strptime_digits(s, i, 2) < 2
        hh = Cybertrain::Cast.number_at(s, i, 2)
        i += 2
        i += 1 if i < n && s.getbyte(i) == 58
        mm = 0
        if strptime_digits(s, i, 2) == 2
          mm = Cybertrain::Cast.number_at(s, i, 2)
          i += 2
        end
        raise ArgumentError, "invalid date: #{text}" if hh > 23 || mm > 59
        offset = (hh * 3600 + mm * 60) * (sign == 45 ? -1 : 1)
      end
    else
      raise ArgumentError, "unsupported strptime directive %#{d}"
    end
  end
  raise ArgumentError, "invalid date: #{text}" if i != n
  return Time.at(epoch).utc if has_epoch

  if yday > 0
    month = 1
    day = 1
  end
  time = Cybertrain::Cast.utc_time(year, month, day, hour, minute, second, usec, offset)
  raise ArgumentError, "invalid date: #{text}" if time.nil?
  return time if yday == 0
  raise ArgumentError, "invalid date: #{text}" if yday == 366 && Cybertrain::Cast.days_in_month(year, 2) == 28
  (time + (yday - 1) * 86400).utc
end

.zone ⇒ Cybertrain::TimeZone

The zone of Cybertrain::Clock.zone: a Cybertrain::TimeZone, UTC by default (Rails answers an ActiveSupport::TimeZone; its name is Time.zone.zone_name).



173
# File 'cybertrain/clock.rb', line 173

def self.zone = Cybertrain::Clock.zone

Instance Method Details

#advance(years: 0, months: 0, weeks: 0, days: 0, hours: 0, minutes: 0, seconds: 0) ⇒ Time

This instant moved by calendar and clock amounts, as Rails’ Time#advance. Years, months, weeks and days move the wall date in Time.zone’s calendar, keeping the wall time of day; a day past the end of the target month is clamped to its last day (31 January plus one month is 28 February, or 29 in a leap year). Hours, minutes and seconds are then added as elapsed seconds. The sub-second part is kept.

Examples:

Time.utc(2026, 1, 31).advance(months: 1) # => 2026-02-28 00:00:00 UTC

Parameters:

Returns:



321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
# File 'cybertrain/time_ext.rb', line 321

def advance(years: 0, months: 0, weeks: 0, days: 0, hours: 0, minutes: 0, seconds: 0)
  epoch = to_i
  if years != 0 || months != 0 || weeks != 0 || days != 0
    zone = Cybertrain::Clock.zone
    wall = Cybertrain::TimeZone.epoch_to_civil(zone.utc_to_local(epoch))
    count = wall[0] * 12 + wall[1] - 1 + years * 12 + months
    year = count.div(12)
    month = count % 12 + 1
    day = wall[2]
    last = Cybertrain::TimeZone.days_in_month(year, month)
    day = last if day > last
    local = Cybertrain::TimeZone.civil_to_epoch(year, month, day + weeks * 7 + days, wall[3], wall[4], wall[5])
    epoch = zone.local_to_utc(local)
  end
  Time.at(epoch + hours * 3600 + minutes * 60 + seconds, usec).utc
end

#beginning_of_day ⇒ Time

The first instant of this instant’s day in Time.zone.

Examples:

With Time.zone Asia/Tokyo

Time.utc(2026, 11, 11, 20).beginning_of_day # => 2026-11-11 15:00:00 UTC

Returns:



241
242
243
244
# File 'cybertrain/time_ext.rb', line 241

def beginning_of_day
  wall = Cybertrain::Calendar.wall(to_i)
  Cybertrain::Calendar.start_of(wall[0], wall[1], wall[2])
end

#beginning_of_month ⇒ Time

The first instant of this instant’s month in Time.zone.

Returns:



275
276
277
278
# File 'cybertrain/time_ext.rb', line 275

def beginning_of_month
  wall = Cybertrain::Calendar.wall(to_i)
  Cybertrain::Calendar.start_of(wall[0], wall[1], 1)
end

#beginning_of_week ⇒ Time

Monday 00:00 of this instant’s week in Time.zone.

Returns:



258
259
260
261
# File 'cybertrain/time_ext.rb', line 258

def beginning_of_week
  wall = Cybertrain::Calendar.wall(to_i)
  Cybertrain::Calendar.start_of(wall[0], wall[1], wall[2] - (wall[6] + 6) % 7)
end

#beginning_of_year ⇒ Time

The first instant of this instant’s year in Time.zone.

Returns:



291
292
293
294
# File 'cybertrain/time_ext.rb', line 291

def beginning_of_year
  wall = Cybertrain::Calendar.wall(to_i)
  Cybertrain::Calendar.start_of(wall[0], 1, 1)
end

#end_of_day ⇒ Time

The last instant of this instant’s day in Time.zone: 23:59:59.999999 (one microsecond before the next day’s beginning).

Returns:



250
251
252
253
# File 'cybertrain/time_ext.rb', line 250

def end_of_day
  wall = Cybertrain::Calendar.wall(to_i)
  Cybertrain::Calendar.end_before(wall[0], wall[1], wall[2] + 1)
end

#end_of_month ⇒ Time

The last instant of this instant’s month in Time.zone.

Returns:



283
284
285
286
# File 'cybertrain/time_ext.rb', line 283

def end_of_month
  wall = Cybertrain::Calendar.wall(to_i)
  Cybertrain::Calendar.end_before(wall[0], wall[1] + 1, 1)
end

#end_of_week ⇒ Time

The last instant of this instant’s week (Sunday 23:59:59.999999) in Time.zone.

Returns:



267
268
269
270
# File 'cybertrain/time_ext.rb', line 267

def end_of_week
  wall = Cybertrain::Calendar.wall(to_i)
  Cybertrain::Calendar.end_before(wall[0], wall[1], wall[2] - (wall[6] + 6) % 7 + 7)
end

#end_of_year ⇒ Time

The last instant of this instant’s year in Time.zone.

Returns:



299
300
301
302
# File 'cybertrain/time_ext.rb', line 299

def end_of_year
  wall = Cybertrain::Calendar.wall(to_i)
  Cybertrain::Calendar.end_before(wall[0] + 1, 1, 1)
end

#in_time_zone(zone = Time.zone) ⇒ Cybertrain::ZonedTime

This instant’s wall fields in zone (spec section 4): a Cybertrain::ZonedTime with year, month, day, hour, min, sec, wday, yday, utc_offset, zone (the abbreviation), to_time and to_date. The Time itself stays a UTC instant.

Examples:

Time.utc(2026, 11, 11, 20).in_time_zone("Asia/Tokyo").hour  # => 5

Parameters:

  • zone (Cybertrain::TimeZone, String) (defaults to: Time.zone) —

    Time.zone when not given; a String is an IANA name (find_zone!). nil is refused (an ArgumentError), where Rails answers the Time itself: one method answers one type here.

Returns:

Raises:

  • (ArgumentError) —

    unknown time zone "Mars/Base"



385
386
387
# File 'cybertrain/time_ext.rb', line 385

def in_time_zone(zone = Time.zone)
  Cybertrain::ZonedTime.new(to_i, Cybertrain::ZonedTime.zone_from(zone), usec)
end

#months_ago(n) ⇒ Time

advance(months: -n).

Parameters:

Returns:



342
# File 'cybertrain/time_ext.rb', line 342

def months_ago(n) = advance(months: -n)

#months_since(n) ⇒ Time

advance(months: n).

Parameters:

Returns:



348
# File 'cybertrain/time_ext.rb', line 348

def months_since(n) = advance(months: n)

#tomorrow ⇒ Time

advance(days: 1): the same wall time the next day in Time.zone.

Returns:



370
# File 'cybertrain/time_ext.rb', line 370

def tomorrow = advance(days: 1)

#years_ago(n) ⇒ Time

advance(years: -n).

Parameters:

Returns:



354
# File 'cybertrain/time_ext.rb', line 354

def years_ago(n) = advance(years: -n)

#years_since(n) ⇒ Time

advance(years: n).

Parameters:

Returns:



360
# File 'cybertrain/time_ext.rb', line 360

def years_since(n) = advance(years: n)

#yesterday ⇒ Time

advance(days: -1): the same wall time the day before in Time.zone.

Returns:



365
# File 'cybertrain/time_ext.rb', line 365

def yesterday = advance(days: -1)