Method: TZInfo::Timezone#local_datetime

Defined in:

lib/tzinfo/timezone.rb

#local_datetime(year, month = 1, day = 1, hour = 0, minute = 0, second = 0, sub_second = 0, dst = Timezone.default_dst) {|periods| ... } ⇒ DateTimeWithOffset

Creates a DateTime object based on the given (Gregorian calendar) date and time parameters. The parameters are interpreted as a local time in the time zone. The result has the appropriate offset and timezone_offset.

Warning: There are time values that are not valid as local times in a time zone (for example, during the transition from standard time to daylight savings time). There are also time values that are ambiguous, occurring more than once with different offsets to UTC (for example, during the transition from daylight savings time to standard time).

In the first case (an invalid local time), a PeriodNotFound exception will be raised.

In the second case (more than one occurrence), an AmbiguousTime exception will be raised unless the optional dst parameter or block handles the ambiguity.

If the ambiguity is due to a transition from daylight savings time to standard time, the dst parameter can be used to select whether the daylight savings time or local time is used. For example, the following code would raise an AmbiguousTime exception:

tz = TZInfo::Timezone.get('America/New_York')
tz.local_datetime(2004,10,31,1,30,0,0)

Specifying dst = true would return a Time with a UTC offset of -4 hours and abbreviation EDT (Eastern Daylight Time). Specifying dst = false would return a Time with a UTC offset of -5 hours and abbreviation EST (Eastern Standard Time).

The dst parameter will not be able to resolve an ambiguity resulting from the clocks being set back without changing from daylight savings time to standard time. In this case, if a block is specified, it will be called to resolve the ambiguity. The block must take a single parameter - an Array of TZInfo::TimezonePeriods that need to be resolved. The block can select and return a single TZInfo::TimezonePeriod or return nil or an empty Array to cause an AmbiguousTime exception to be raised.

The default value of the dst parameter can be specified using default_dst=.

values, interpreted as a local time in the time zone.

Parameters:

• year (Integer) —

  the year.

• month (Integer) (defaults to: 1) —

  the month (1-12).

• day (Integer) (defaults to: 1) —

  the day of the month (1-31).

• hour (Integer) (defaults to: 0) —

  the hour (0-23).

• minute (Integer) (defaults to: 0) —

  the minute (0-59).

• second (Integer) (defaults to: 0) —

  the second (0-59).

• sub_second (Numeric) (defaults to: 0) —

  the fractional part of the second as either a Rational that is greater than or equal to 0 and less than 1, or the Integer 0.

• dst (Boolean) (defaults to: Timezone.default_dst) —

  whether to resolve ambiguous local times by always selecting the period observing daylight savings time (true), always selecting the period observing standard time (false), or leaving the ambiguity unresolved (nil).

Yields:

• (periods) —

  if the dst parameter did not resolve an ambiguity, an optional block is yielded to.

Yield Parameters:

• periods (Array<TimezonePeriod>) —

  an Array containing all the TZInfo::TimezonePeriods that still match local_time after applying the dst parameter.

Yield Returns:

• (Object) —

  to resolve the ambiguity: a chosen TZInfo::TimezonePeriod or an Array containing a chosen TZInfo::TimezonePeriod; to leave the ambiguity unresolved: an empty Array, an Array containing more than one TZInfo::TimezonePeriod, or nil.

Returns:

• (DateTimeWithOffset) —

  a new DateTime object based on the given

Raises:

• (ArgumentError) —

  if either of year, month, day, hour, minute, or second is not an Integer.

• (ArgumentError) —

  if sub_second is not a Rational, or the Integer 0.

• (ArgumentError) —

  if utc_offset is not nil, not an Integer and not the Symbol :utc.

• (RangeError) —

  if month is not between 1 and 12.

• (RangeError) —

  if day is not between 1 and 31.

• (RangeError) —

  if hour is not between 0 and 23.

• (RangeError) —

  if minute is not between 0 and 59.

• (RangeError) —

  if second is not between 0 and 59.

• (RangeError) —

  if sub_second is a Rational but that is less than 0 or greater than or equal to 1.

• (PeriodNotFound) —

  if the date and time parameters do not specify a valid local time in the time zone.

• (AmbiguousTime) —

  if the date and time parameters are ambiguous for the time zone and the dst parameter or block did not resolve the ambiguity.

# File 'lib/tzinfo/timezone.rb', line 831

def local_datetime(year, month = 1, day = 1, hour = 0, minute = 0, second = 0, sub_second = 0, dst = Timezone.default_dst, &block)
  local_timestamp(year, month, day, hour, minute, second, sub_second, dst, &block).to_datetime
end