Class: Cybertrain::TimeZone
- Inherits:
-
Object
- Object
- Cybertrain::TimeZone
- 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.
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
-
.civil_to_epoch(year, month, day, hour, minute, second) ⇒ Integer
Epoch seconds of a civil date and time, counted as UTC.
-
.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).
-
.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). -
.find(name) ⇒ TimeZone
The zone named name, read from
$TZDIR/<name>(default/usr/share/zoneinfo/<name>) the first time and cached after that. -
.parse_tzif(name, bytes) ⇒ TimeZone
Parses the bytes of a TZif file (RFC 8536, versions 1 to 4).
-
.valid_name?(name) ⇒ Boolean
True for a name TimeZone.find will look up: 1 to 255 bytes of
A-Za-z0-9_+-./, relative, with no empty,.or..segment. -
.zoneinfo_dir ⇒ String
The directory zone names resolve under:
TZDIR, or DEFAULT_DIR.
Instance Method Summary collapse
-
#abbreviation_at(epoch) ⇒ String
The abbreviation in use at an instant (“JST”, “EDT”, “+09”).
-
#dst_at?(epoch) ⇒ Boolean
True when the instant falls in daylight saving time.
-
#found? ⇒ Boolean
False when TimeZone.find could not resolve or parse the name; the zone then behaves as UTC.
-
#local_to_utc(local_epoch) ⇒ Integer
The UTC instant of a local epoch.
-
#unknown? ⇒ Boolean
The opposite of #found?.
-
#utc_offset_at(epoch) ⇒ Integer
The UTC offset in seconds (east positive: 32400 for JST) at an instant.
-
#utc_to_local(utc_epoch) ⇒ Integer
The local epoch (the wall clock counted as if it were UTC) of a UTC instant.
-
#zone_name ⇒ String
The name the zone was asked for (“Asia/Tokyo”).
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).
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).
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.
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.
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.
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 = PosixTz.none = PosixTz.parse((s, at + size)) if wide TimeZone.new(name, true, times, type_of, utoffs, dsts, abbrs, ) 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.
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.
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”).
422 423 424 425 426 427 428 429 430 |
# File 'cybertrain/time_zone.rb', line 422 def abbreviation_at(epoch) t = epoch.to_i = @tz_footer if (t) return .dst_in_effect?(t) ? .dst_abbr : .std_abbr end @tz_abbrs[type_at(t)] end |
#dst_at?(epoch) ⇒ Boolean
True when the instant falls in daylight saving time.
410 411 412 413 414 415 416 |
# File 'cybertrain/time_zone.rb', line 410 def dst_at?(epoch) t = epoch.to_i = @tz_footer return .dst_in_effect?(t) if (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.
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.
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?.
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.
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 = @tz_footer if (t) return .dst_in_effect?(t) ? .dst_utoff : .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.
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”).
373 374 375 |
# File 'cybertrain/time_zone.rb', line 373 def zone_name @tz_name end |