Class: Cybertrain::TimeZone

Inherits:
Object
  • Object
show all
Defined in:
cybertrain/time_zone.rb

Overview

A named time zone, parsed from a TZif file under the zoneinfo directory and cached for the life of the process. A zone is immutable once parsed, so one instance is shared by every thread.

Times are Integer epoch seconds. A local epoch is a wall-clock reading counted as if it were UTC (TimeZone.civil_to_epoch(2026, 3, 8, 9, 0, 0) is 09:00 on 8 March, wherever); #utc_to_local and #local_to_utc convert between the two, so “tomorrow at 09:00 in Tokyo” is: convert now to local, take the civil date, add a day, rebuild 09:00 and convert back.

Unknown names do not raise: TimeZone.find answers a zone that behaves as UTC and whose #found? is false, so the caller can log a warning.

Examples:

The next 09:00 in Asia/Tokyo after now

tokyo = Cybertrain::TimeZone.find("Asia/Tokyo")
now = Time.current.to_i
today = Cybertrain::TimeZone.epoch_to_civil(tokyo.utc_to_local(now))
run = tokyo.local_to_utc(Cybertrain::TimeZone.civil_to_epoch(today[0], today[1], today[2], 9, 0, 0))
run = tokyo.local_to_utc(Cybertrain::TimeZone.civil_to_epoch(today[0], today[1], today[2] + 1, 9, 0, 0)) if run <= now

Constant Summary collapse

UTC =

UTC: offset 0, no transitions, found.

TimeZone.new("UTC", true, Array.new(0) { 0 }, Array.new(0) { 0 }, [0], [0], ["UTC"], PosixTz.parse("UTC0"))

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.civil_to_epoch(year, month, day, hour, minute, second) ⇒ Integer

Epoch seconds of a civil date and time, counted as UTC. Pass a local wall-clock reading to get a local epoch for #local_to_utc. Out-of-range fields roll over (hour 24 is the next day).

Returns:



536
537
538
# File 'cybertrain/time_zone.rb', line 536

def self.civil_to_epoch(year, month, day, hour, minute, second)
  days_from_civil(year, month, day) * 86_400 + hour * 3600 + minute * 60 + second
end

.days_from_civil(year, month, day) ⇒ Integer

Days since 1970-01-01 of a proleptic Gregorian date (month and day may run past their range: day 32 of January is February 1).

Parameters:

Returns:



519
520
521
522
523
524
525
526
527
528
529
# File 'cybertrain/time_zone.rb', line 519

def self.days_from_civil(year, month, day)
  y = year + (month - 1).div(12)
  m = (month - 1) % 12 + 1
  y -= 1 if m <= 2
  era = y.div(400)
  yoe = y - era * 400
  mp = (m + 9) % 12
  doy = (153 * mp + 2) / 5 + day - 1
  doe = yoe * 365 + yoe / 4 - yoe / 100 + doy
  era * 146_097 + doe - 719_468
end

.epoch_to_civil(epoch) ⇒ Array<Integer>

The civil fields of an epoch counted as UTC: [year, month, day, hour, minute, second, wday] (wday 0 = Sunday). Pass a local epoch from #utc_to_local to read the wall clock.

Parameters:

Returns:



546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
# File 'cybertrain/time_zone.rb', line 546

def self.epoch_to_civil(epoch)
  e = epoch.to_i
  days = e.div(86_400)
  secs = e - days * 86_400
  z = days + 719_468
  era = z.div(146_097)
  doe = z - era * 146_097
  yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365
  doy = doe - (365 * yoe + yoe / 4 - yoe / 100)
  mp = (5 * doy + 2) / 153
  day = doy - (153 * mp + 2) / 5 + 1
  month = mp < 10 ? mp + 3 : mp - 9
  year = yoe + era * 400 + (month <= 2 ? 1 : 0)
  [year, month, day, secs / 3600, (secs % 3600) / 60, secs % 60, (days + 4) % 7]
end

.find(name) ⇒ TimeZone

The zone named name, read from $TZDIR/<name> (default /usr/share/zoneinfo/<name>) the first time and cached after that. “UTC” is built in and needs no file. A name that is not a plain relative path under the directory (absolute, .. or . segments, characters outside A-Za-z0-9_+-./), a missing file or one that is not valid TZif gives a zone that behaves as UTC with #found? false; those are not cached.

Readers acquire the snapshot under the writer’s Mutex, then look up the immutable snapshot outside it. File I/O and parsing hold no lock.

Parameters:

  • name (String) —

    an IANA zone name such as “Asia/Tokyo”

Returns:



589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
# File 'cybertrain/time_zone.rb', line 589

def self.find(name)
  key = name.to_s
  return UTC if key == "UTC"
  return unknown(key) unless valid_name?(key)

  dir = zoneinfo_dir
  path = "#{dir}/#{key}"
  cache = zone_cache_snapshot
  i = cache.zone_index(path)
  return cache.zone_at(i) if i >= 0

  zone = load_file(key, path)
  return zone unless zone.found?

  remember_zone(path, zone)
end

.parse_tzif(name, bytes) ⇒ TimeZone

Parses the bytes of a TZif file (RFC 8536, versions 1 to 4). For version 2 and later the 32-bit block is skipped and the 64-bit block and the footer are read. Malformed input gives a zone whose #found? is false.

Parameters:

  • name (String) —

    the name to report

  • bytes (String) —

    the file’s contents

Returns:



702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
# File 'cybertrain/time_zone.rb', line 702

def self.parse_tzif(name, bytes)
  s = bytes.to_s
  return unknown(name) unless tzif_magic?(s, 0)

  version = s.getbyte(4)
  wide = version >= 50
  pos = 0
  if wide
    v1 = block_bytes(s, 0, 4)
    return unknown(name) if v1 < 0

    pos = 44 + v1
    return unknown(name) unless tzif_magic?(s, pos)
  end
  width = wide ? 8 : 4
  size = block_bytes(s, pos, width)
  return unknown(name) if size < 0

  timecnt = be32(s, pos + 32)
  typecnt = be32(s, pos + 36)
  charcnt = be32(s, pos + 40)
  at = pos + 44
  types_at = at + timecnt * width
  ttinfo_at = types_at + timecnt
  chars_at = ttinfo_at + typecnt * 6

  times = Array.new(0) { 0 }
  type_of = Array.new(0) { 0 }
  i = 0
  while i < timecnt
    t = wide ? be64(s, at + i * 8) : be32_signed(s, at + i * 4)
    return unknown(name) if i.positive? && t <= times[i - 1]

    idx = s.getbyte(types_at + i)
    return unknown(name) if idx >= typecnt

    times << t
    type_of << idx
    i += 1
  end

  utoffs = Array.new(0) { 0 }
  dsts = Array.new(0) { 0 }
  abbrs = Array.new(0) { "" }
  i = 0
  while i < typecnt
    base = ttinfo_at + i * 6
    isdst = s.getbyte(base + 4)
    abbrind = s.getbyte(base + 5)
    return unknown(name) if isdst > 1 || abbrind >= charcnt

    abbr = abbreviation(s, chars_at + abbrind, chars_at + charcnt)
    return unknown(name) if abbr.empty?

    utoffs << be32_signed(s, base)
    dsts << isdst
    abbrs << abbr
    i += 1
  end

  footer = PosixTz.none
  footer = PosixTz.parse(footer_text(s, at + size)) if wide
  TimeZone.new(name, true, times, type_of, utoffs, dsts, abbrs, footer)
end

.valid_name?(name) ⇒ Boolean

True for a name find will look up: 1 to 255 bytes of A-Za-z0-9_+-./, relative, with no empty, . or .. segment.

Parameters:

  • name (String)

Returns:

  • (Boolean)


619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
# File 'cybertrain/time_zone.rb', line 619

def self.valid_name?(name)
  s = name.to_s
  n = s.bytesize
  return false if n.zero? || n > MAX_NAME_BYTES

  seg_len = 0
  seg_dots = 0
  i = 0
  while i < n
    c = s.getbyte(i)
    if c == 47
      return false if seg_len.zero? || seg_dots == seg_len

      seg_len = 0
      seg_dots = 0
    elsif (c >= 65 && c <= 90) || (c >= 97 && c <= 122) || (c >= 48 && c <= 57) ||
          c == 95 || c == 43 || c == 45 || c == 46
      seg_len += 1
      seg_dots += 1 if c == 46
    else
      return false
    end
    i += 1
  end
  seg_len.positive? && seg_dots != seg_len
end

.zoneinfo_dir ⇒ String

The directory zone names resolve under: TZDIR, or DEFAULT_DIR.

Returns:

  • (String)


609
610
611
612
# File 'cybertrain/time_zone.rb', line 609

def self.zoneinfo_dir
  dir = ENV["TZDIR"].to_s
  dir.empty? ? DEFAULT_DIR : dir
end

Instance Method Details

#abbreviation_at(epoch) ⇒ String

The abbreviation in use at an instant (“JST”, “EDT”, “+09”).

Parameters:

  • epoch (Integer) —

    UTC epoch seconds

Returns:

  • (String)


422
423
424
425
426
427
428
429
430
# File 'cybertrain/time_zone.rb', line 422

def abbreviation_at(epoch)
  t = epoch.to_i
  footer = @tz_footer
  if footer_applies?(t)
    return footer.dst_in_effect?(t) ? footer.dst_abbr : footer.std_abbr
  end

  @tz_abbrs[type_at(t)]
end

#dst_at?(epoch) ⇒ Boolean

True when the instant falls in daylight saving time.

Parameters:

  • epoch (Integer) —

    UTC epoch seconds

Returns:

  • (Boolean)


410
411
412
413
414
415
416
# File 'cybertrain/time_zone.rb', line 410

def dst_at?(epoch)
  t = epoch.to_i
  footer = @tz_footer
  return footer.dst_in_effect?(t) if footer_applies?(t)

  @tz_dsts[type_at(t)] == 1
end

#found? ⇒ Boolean

False when find could not resolve or parse the name; the zone then behaves as UTC.

Returns:

  • (Boolean)


381
382
383
# File 'cybertrain/time_zone.rb', line 381

def found?
  @tz_found
end

#local_to_utc(local_epoch) ⇒ Integer

The UTC instant of a local epoch. Deterministic at transitions:

  • in a gap (a wall time skipped by a forward jump, 02:30 on a US spring-forward day), the local time is read with the offset in effect before the transition, which lands after it (02:30 EST is 03:30 EDT);
  • in an overlap (a wall time repeated by a backward jump), the earlier of the two instants is returned (01:30 EDT, not 01:30 EST). Assumes at most one transition within a day of the local time, which holds for every zone in the tz database.

Parameters:

Returns:



454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
# File 'cybertrain/time_zone.rb', line 454

def local_to_utc(local_epoch)
  local = local_epoch.to_i
  before = utc_offset_at(local - 86_400)
  after = utc_offset_at(local + 86_400)
  early = local - before
  late = local - after
  early_ok = utc_offset_at(early) == before
  late_ok = utc_offset_at(late) == after
  if early_ok && late_ok
    early < late ? early : late
  elsif late_ok
    late
  else
    early
  end
end

#unknown? ⇒ Boolean

The opposite of #found?.

Returns:

  • (Boolean)


388
389
390
# File 'cybertrain/time_zone.rb', line 388

def unknown?
  !@tz_found
end

#utc_offset_at(epoch) ⇒ Integer

The UTC offset in seconds (east positive: 32400 for JST) at an instant.

Parameters:

  • epoch (Integer) —

    UTC epoch seconds

Returns:



396
397
398
399
400
401
402
403
404
# File 'cybertrain/time_zone.rb', line 396

def utc_offset_at(epoch)
  t = epoch.to_i
  footer = @tz_footer
  if footer_applies?(t)
    return footer.dst_in_effect?(t) ? footer.dst_utoff : footer.std_utoff
  end

  @tz_utoffs[type_at(t)]
end

#utc_to_local(utc_epoch) ⇒ Integer

The local epoch (the wall clock counted as if it were UTC) of a UTC instant.

Parameters:

Returns:



437
438
439
440
# File 'cybertrain/time_zone.rb', line 437

def utc_to_local(utc_epoch)
  t = utc_epoch.to_i
  t + utc_offset_at(t)
end

#zone_name ⇒ String

The name the zone was asked for (“Asia/Tokyo”).

Returns:

  • (String)


373
374
375
# File 'cybertrain/time_zone.rb', line 373

def zone_name
  @tz_name
end