Class: TZTime::LocalTime::Builder

Inherits:
Object
  • Object
show all
Defined in:
lib/tztime/local_time/builder.rb

Overview

An instance of LocalTime::Builder is used to generate LocalTime instances based on the time_zone of the Builder. The LocalTime instances wrap a Time instance that has properties reflective of time_zone. The Time values themselves are represented internally as UTC, but the time has been offset by the time_zone. This is due to a limitation of the Time class in Ruby.

The Builder is created by passing in either a String that names a time zone, or a TZInfo time zone definition. The String name can be either the format used by TZInfo or Rails.

Usage

Create a new Builder for the time zone in New York.

builder = TZTime::LocalTime::Builder.new('America/New_York')
puts builder.time_zone_name  # => America/New_York

Underneath, this will have the same TZInfo time zone definition as above.

builder = TZTime::LocalTime::Builder.new('Eastern Time (US & Canada)')
puts builder.time_zone_name  # => Eastern Time (US & Canada)

now will create the current day and time, while today will create the current day with time at 0:00. Both of these will be converted to the time_zone of the Builder instance.

puts builder.now    # => 2007-12-12 22:28:09 EST
puts builder.today  # => 2007-12-12 00:00:00 EST

The Builder can also create LocalTime instances at specific times using local and utc. local assumes the values passed in are expressed in the time_zone, while utc assumes the values are in Univeral Time and need to be converted into the time_zone time.

puts builder.utc(2007, 12, 13, 3, 36, 26)     # => 2007-12-12 22:36:26 EST
puts builder.local(2007, 12, 13, 3, 36, 26)   # => 2007-12-13 03:36:26 EST
puts builder.local(2007, 12, 12, 22, 36, 26)  # => 2007-12-12 22:36:26 EST

Using, at_local and at_utc, the Builder can convert existing time values into localized values. at_local assumes time values represent the current time_zone, ignoring the time zone of the value. at_utc assumes the time values represent Universal Time values while still ignoring the time zone of the value.

time = Time.utc(2007, 12, 13, 3, 36, 26)
puts builder.at_utc(time)    # => 2007-12-12 22:36:26 EST
puts builder.at_local(time)  # => 2007-12-13 03:36:26 EST

time = Time.local(2007, 12, 13, 3, 36, 26)
puts builder.at_utc(time)    # => 2007-12-12 22:36:26 EST
puts builder.at_local(time)  # => 2007-12-13 03:36:26 EST

at is aliased to at_local, so it can be used instead.

Converting from a seperate time zone into the builder’s time zone can be done with the convert method. This will convert from the time zone of the time value. Optionally, an explicit time zone can be specified:

builder = TZTime::LocalTime::Builder.new('America/Los_Angeles')
time = Time.now
# time zone is EDT
puts time # => Thu Apr 10 18:42:40 -0400 2008
puts builder.convert(time) # => 2008-04-10 15:42:40 PDT
puts builder.convert(time, 'America/Chicago') # => 2008-04-10 16:42:40 PDT

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(time_zone) ⇒ Builder

Creates a new LocalTime::Builder that can create LocalTime instances relative to the given time zone.

The time_zone must be either a String that names a time zone, or an instance of a TZInfo time zone definition. The String name can be either the format used by TZInfo or Rails.

If a String name is passed in, this value will be retained and accessible by time_zone_name. If a TZInfo time zone definition value is passed, then time_zone_name will return the name attribute of the TZInfo time zone definition.



88
89
90
91
92
93
94
95
96
97
 
# File 'lib/tztime/local_time/builder.rb', line 88

def initialize(time_zone)
  if time_zone.is_a?(String)
    @time_zone = self.class.get_time_zone(time_zone)
    @time_zone_name = time_zone
  else
    @time_zone = time_zone
    @time_zone_name = time_zone.name
  end
  freeze
end

Class Method Details

.get_time_zone(name) ⇒ Object

Gets a time zone instance for a given name. The name can be either the names used by TZInfo or the TimeZone class in ActiveSupport.



73
74
75
 
# File 'lib/tztime/local_time/builder.rb', line 73

def self.get_time_zone(name)
  TZInfo::Timezone.get(RAILS_CONVERSIONS[name] || name)
end

.utc ⇒ Object

Uses get to acquire a Builder instance in the UTC time zone.



67
68
69
 
# File 'lib/tztime/local_time/builder.rb', line 67

def self.utc
  new('UTC')
end

Instance Method Details

#at_local(*args) ⇒ Object Also known as: at

call-seq:

at_local(time) => LocalTime
at_local(second [, microseconds]) => LocalTime
at(time) => LocalTime
at(second [, microseconds]) => LocalTime

Takes a Time instance and returns a LocalTime instance. The time is read as if in the timezone of this Builder instance, regardless of the time zone value. However, if a LocalTime instance is passed in, the proper conversion will take place.



208
209
210
 
# File 'lib/tztime/local_time/builder.rb', line 208

def at_local(*args)
  extract_and_create_local_time(args, true)
end

#at_utc(*args) ⇒ Object Also known as: at_gm

call-seq:

at_utc(time) => LocalTime
at_utc(second [, microseconds]) => LocalTime
at_gm(time) => LocalTime
at_gm(second [, microseconds]) => LocalTime

Takes a Time instance and returns a LocalTime instance. The time is read as if in universal time and converted to the, regardless of the time zone value. However, if a LocalTime instance is passed in, the proper conversion will take place.



224
225
226
 
# File 'lib/tztime/local_time/builder.rb', line 224

def at_utc(*args)
  extract_and_create_local_time(args, false)
end

#convert(local_time, from_time_zone = nil) ⇒ Object

Creates a new LocalTime instance converted from local_time‘s time zone into this time zone. If local_time is in the same time zone, then local_time will be returned. If local_time is not an instance of LocalTime, then from_time_zone must be passed in. from_time_zone will be ignored if local_time is an instance of LocalTime.



235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/tztime/local_time/builder.rb', line 235

def convert(local_time, from_time_zone=nil)
  if from_time_zone
    b = self.class.new(from_time_zone)
    t = b.at(local_time).getutc
    utc(t.year, t.month, t.day, t.hour, t.min, t.sec, t.usec)
  elsif local_time.respond_to?(:getutc)
    t = local_time.getutc
    utc(t.year, t.month, t.day, t.hour, t.min, t.sec, t.usec)
  else
    nil
  end
end

#day_at_local(time, *args) ⇒ Object Also known as: day_at

call-seq:

day_at_local(time  [, min, sec, usec]) => LocalTime
day_at(time  [, min, sec, usec]) => LocalTime

Create a new LocalTime object representing the day in time and the specified time. The time values are assumed to be in local time_zone.



156
157
158
 
# File 'lib/tztime/local_time/builder.rb', line 156

def day_at_local(time, *args)
  local(time.year, time.month, time.day, *args)
end

#day_at_utc(time, *args) ⇒ Object Also known as: day_at_gm

call-seq:

day_at_utc(time  [, min, sec, usec]) => LocalTime
day_at_gm(time  [, min, sec, usec]) => LocalTime

Create a new LocalTime object representing the day in time and the specified time. The time values are assumed to be in Universal Time and will be converted to the time_zone.



169
170
171
 
# File 'lib/tztime/local_time/builder.rb', line 169

def day_at_utc(time, *args)
  utc(time.year, time.month, time.day, *args)
end

#local(*args) ⇒ Object

call-seq:

local(year [, month, day, hour, min, sec, usec]) => LocalTime
local(sec, min, hour, day, month, year, wday, yday, isdst, tz) => LocalTime

Create a LocalTime where the arguments are expressed locally to the time_zone.



180
181
182
 
# File 'lib/tztime/local_time/builder.rb', line 180

def local(*args)
  create(Time.utc(*args))
end

#now ⇒ Object

Create a new LocalTime object representing the current day and time in the given time_zone.



114
115
116
 
# File 'lib/tztime/local_time/builder.rb', line 114

def now
  create(@time_zone.utc_to_local(Time.now.utc))
end

#time_zone ⇒ Object

The TZInfo time zone instance



108
109
110
 
# File 'lib/tztime/local_time/builder.rb', line 108

def time_zone
  @time_zone
end

#time_zone_name ⇒ Object

The name of the time zone. This will reflect the name that was passed to new. If a rails-style time zone name was used, this will return that value. Otherwise it will return the name attribute from the TZInfo time zone definition.



103
104
105
 
# File 'lib/tztime/local_time/builder.rb', line 103

def time_zone_name
  @time_zone_name
end

#today ⇒ Object

Create a new LocalTime object representing the current day in the given time_zone.



120
121
122
123
 
# File 'lib/tztime/local_time/builder.rb', line 120

def today
  time = @time_zone.utc_to_local(Time.now.utc)
  create(Time.utc(time.year, time.month, time.day))
end

#today_at_local(*args) ⇒ Object Also known as: today_at

call-seq:

today_at_local(hour [, min, sec, usec]) => LocalTime
today_at(hour [, min, sec, usec]) => LocalTime

Create a new LocalTime object representing the current day and the specified time. The time values are assumed to be in local time_zone.



131
132
133
 
# File 'lib/tztime/local_time/builder.rb', line 131

def today_at_local(*args)
  day_at_local(today, *args)
end

#today_at_utc(*args) ⇒ Object Also known as: today_at_gm

call-seq:

today_at_utc(hour [, min, sec, usec]) => LocalTime
today_at_gm(hour [, min, sec, usec]) => LocalTime

Create a new LocalTime object representing the current day and the specified time. The time values are assumed to be in Universal Time and will be converted to the time_zone.



144
145
146
 
# File 'lib/tztime/local_time/builder.rb', line 144

def today_at_utc(*args)
  day_at_utc(today, *args)
end

#utc(*args) ⇒ Object Also known as: gm

call-seq:

utc(year [, month, day, hour, min, sec, usec]) => LocalTime
utc(sec, min, hour, day, month, year, wday, yday, isdst, tz) => LocalTime
gm(year [, month, day, hour, min, sec, usec]) => LocalTime
gm(sec, min, hour, day, month, year, wday, yday, isdst, tz) => LocalTime

Create a LocalTime where the arguments are expressed in UTC. This will convert the time value into the local time_zone.



192
193
194
 
# File 'lib/tztime/local_time/builder.rb', line 192

def utc(*args)
  create(@time_zone.utc_to_local(Time.utc(*args)))
end