4Suite™ API Documentation

# ► Module Ft.Lib.Time

Date and time related functionality for use within 4Suite only.

    This module is experimental and may not be staying in 4Suite for long;
    application developers should avoid forming dependencies on it.

    Copyright 2005 Fourthought, Inc. (USA).
    Detailed license and copyright information: http://4suite.org/COPYRIGHT
    Project home, documentation, distributions: http://4suite.org/

Classes: DT |  |  |  | Functions: DayOfYearFromYMD, FromISO8601, FromPythonTime, FromPythonTimeTuple, FromRFC822, WeekdayFromYMD, isDST |  |  |  | Globals: g_isoExpressions

## Classes

class DT
  A class that contains the data needed to represent a single point in time using many different date and time formats.

      Its constructor requires a UTC (GMT) date and time (year, month (0-11), day
      (0-31), hour (0-23), minute (0-59), second (0-59), millisecond (0-999), plus
      some information to help express this time in local terms: a local time zone
      name, or if that's not available, an hour offset of the local time from GMT
      (-11 to 14, typically), a minute offset of the local time from GMT (0 or 30,
      usually), and an optional flag indicating Daylight Savings Time, to help
      determine the time zone name.

  ### Methods

  __cmp__(self, other)
  __hash__(self)
  __init__(self, year, month, day, hour, minute, second, milliSecond, daylightSavings, tzName, tzHourOffset, tzMinuteOffset)
  __str__ = asISO8601DateTime(self, local=0)
    Represents this DT object as an ISO 8601 date-time string, using UTC time like '2001-01-01T00:00:00Z' if local=0, or local time with UTC offset like '2000-12-31T17:00:00-07:00' if local=1.
  abbreviatedMonthName(self, local=0)
    Returns the month component of the stored date and time as a string like 'Jan'.
  asISO8601Date(self, local=0)
    Represents this DT object as an ISO 8601 date-time string, like '2001-01-01' if local=0, or '2000-12-31' if local=1. The local date may vary from UTC date depending on the time of day that is stored in the object.
  asISO8601DateTime(self, local=0)
    Represents this DT object as an ISO 8601 date-time string, using UTC time like '2001-01-01T00:00:00Z' if local=0, or local time with UTC offset like '2000-12-31T17:00:00-07:00' if local=1.
  asISO8601Time(self, local=0)
    Represents this DT object as an ISO 8601 time string, using UTC time like 'T00:00:00Z' if local=0, or local time with UTC offset like 'T17:00:00-07:00' if local=1
  asPythonTime(self, local=0)
    Returns the stored date and time as a float indicating the number of seconds since the local machine's epoch.
  asPythonTimeTuple(self, local=0)
    Returns the stored date and time as a Python time tuple, as documented in the time module. If the tuple is going to be passed to a function that expects the local time, set local=1. The Daylight Savings flag is always -1, which means unknown, and may or may not have ramifications.
  asRFC822DateTime(self, local=0)
    Represents this DT object as an RFC 1123 (which updated RFC 822) date string, using UTC time like 'Mon, 01 Jan 2001 00:00:00 GMT' if local=0, or local time with time zone indicator or offset like 'Sun, 31 Dec 2000 17:00:00 MDT' if local=1. Although RFC 822 allows the weekday to be optional, it is always included in the returned string.
  day(self, local=0)
    Returns the day component of the stored date and time as an integer in the range 1-31.
  dayOfWeek(self, local=0)
    Returns the day of week component of the stored date and time as an int in the range 0-6 (0=Monday).
  dayOfYear(self, local=0)
    Returns the day of year component of the stored date and time as an int in the range 1-366.
  hour(self, local=0)
    Returns the hour component of the stored date and time as an int in the range 0-23.
  milliSecond(self)
    Returns the millisecond component of the stored date and time as an int in the range 0-999.
  minute(self, local=0)
    Returns the minute component of the stored date and time as an int in the range 0-59.
  month(self, local=0)
    Returns the month component of the stored date and time as an int in the range 0-11.
  monthName(self, local=0)
    Returns the month component of the stored date and time as a string like 'January'.
  second(self)
    Returns the second component of the stored date and time as an int in the range 0-59.
  tzHourOffset(self)
    Returns the local time's hour offset from GMT component of the stored date and time as an int, typically in the range -12 to 14.
  tzMinuteOffset(self)
    Returns the local time's minute offset from GMT component of the stored date and time as an int in the range 0-59.
  tzName(self)
    Returns the local time's time zone name component of the stored date and time as a string like 'MST'.
  year(self, local=0)
    Returns the year component of the stored date and time as an int like 2001.

  ### Members

  abbreviatedMonthNameTable = ('ERR', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec')
  abbreviatedWeekdayNameTable = ('Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun')
  monthNameTable = ('ERROR', 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December')
  tzNameTable = {-12: ('GMT-11', 'Yankee', 'IDLW', ''), -11: ('GMT-11', 'XRay', 'NT', ''), -10: ('GMT-10', 'Whiskey', 'AHST', ''), -9.5: ('GMT-9:30', '', '', 'HDT'), -9: ('GMT-9', 'Victor', 'YST', ''), -8.5: ('GMT-8:30', '', '', 'YDT'), -8: ('GMT-8', 'Uniform', 'PST', ''), -7: ('GMT-7', 'Tango', 'MST', 'PDT'), -6: ('GMT-6', 'Sierra', 'CST', 'MDT'), -5: ('GMT-5', 'Romeo', 'EST', 'CDT'), ...}
  weekdayNameTable = ('Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday')

## Functions

DayOfYearFromYMD(year, month, day)
  Calculates the Julian day (day of year, between 1 and 366), for the given date. This function is accurate for dates back to 01 Jan 0004 (that's 4 A.D.), when the Julian calendar stabilized.
FromISO8601(st)
  Create a DT object from an ISO 8601 date, time or date-time string. The DT object must contain a complete date and time, and the ISO 8601 string might represent a partial date or time, so some assumptions are made about the 'implied' information (ISO 8601's terminology).
FromPythonTime(t=None)
  Create a DT object from a float that represents seconds elapsed since the local machine's epoch. If not specified, then current time is used.
FromPythonTimeTuple(t)
  Create a DT object from a Python time tuple as documented in the time module. This 9-tuple must represent a UTC date and time.
FromRFC822(st)
  Create a DT object from an RFC 822/1123 date string
WeekdayFromYMD(year, month, day)
  Calculates the day of week (0=Mon, 6=Sun) for the given date. This function is accurate for dates on/after Friday, 15 Oct 1582, when the Gregorian reform took effect, although it should be noted that some nations didn't adopt the Gregorian calendar until as late as the 20th century, so dates that were referenced before then would have fallen on a different day of the week, at the time.
isDST(t)
  Indicates whether the given UTC time tuple corresponds to a date and time that falls during Daylight Savings Time in the local time zone.

## Globals

g_isoExpressions = [['^(?P<Date>(?P<CalendarDate>(?P<Century>[0-9]{2,2...{2,2})(?P<Month>[0-9]{2,2})(?P<Day>[0-9]{2,2})))$', None], ['^(?P<Date>(?P<CalendarDate>(?P<Century>[0-9]{2,2...,2})-(?P<Month>[0-9]{2,2})-(?P<Day>[0-9]{2,2})))$', None], ['^(?P<Date>(?P<CalendarDate>(-|(?P<Century>[0-9]{2,2}))(?P<Year>[0-9]{2,2})-(?P<Month>[0-9]{2,2})))$', None], ['^(?P<Date>(?P<CalendarDate>-(?P<Year>[0-9]{2,2})(?P<Month>[0-9]{2,2})))$', None], ['^(?P<Date>(?P<CalendarDate>(-|(?P<Century>[0-9]{2,2}))(?P<Year>[0-9]{2,2})))$', None], ['^(?P<Date>(?P<CalendarDate>(?P<Century>[0-9]{2,2})))$', None], ['^(?P<Date>(?P<CalendarDate>--(?P<Month>[0-9]{2,2})(?:-?(?P<Day>[0-9]{2,2}))?))$', None], ['^(?P<Date>(?P<CalendarDate>---(?P<Day>[0-9]{2,2})))$', None], ['^(?P<Date>(?P<OrdinalDate>(?P<Century>[0-9]{2,2})?(?P<Year>[0-9]{2,2})-?(?P<Ordinal>[0-9]{3,3})))$', None], ['^(?P<Date>(?P<OrdinalDate>-(?P<Ordinal>[0-9]{3,3})))$', None], ['^(?P<Date>(?P<WeekDate>(?P<Century>[0-9]{2,2})?(...{2,2})W(?P<Week>[0-9][0-9])(?P<Weekday>[1-7])?))$', None], ['^(?P<Date>(?P<WeekDate>(?P<Century>[0-9]{2,2})?(...-W(?P<Week>[0-9][0-9])(?:-(?P<Weekday>[1-7]))?))$', None], ['^(?P<Date>(?P<WeekDate>-(?P<YearInDecade>[0-9])W(?P<Week>[0-9][0-9])(?P<Weekday>[1-7])))$', None], ['^(?P<Date>(?P<WeekDate>-(?P<YearInDecade>[0-9])-W(?P<Week>[0-9][0-9])-(?P<Weekday>[1-7])))$', None], ['^(?P<Date>(?P<WeekDate>-W(?P<Week>[0-9][0-9])(?:-?(?P<Weekday>[1-7]))?))$', None], ['^(?P<Date>(?P<WeekDate>-W?-(?P<Weekday>[1-7])))$', None], ['^(?P<Time>(?:(?P<Hour>(?:0[0-9])|(?:1[0-9])|(?:2...]))(?::?(?P<TzMinute>(?:[0-5][0-9])|(?:60)))?))?$', None], ['^(?P<Time>(?:(?P<Hour>(?:0[0-9])|(?:1[0-9])|(?:2...]))(?::?(?P<TzMinute>(?:[0-5][0-9])|(?:60)))?))?$', None], ['^(?P<Time>(?:(?P<Hour>(?:0[0-9])|(?:1[0-9])|(?:2...]))(?::?(?P<TzMinute>(?:[0-5][0-9])|(?:60)))?))?$', None], ['^(?P<Time>(?:(?P<Hour>(?:0[0-9])|(?:1[0-9])|(?:2...]))(?::?(?P<TzMinute>(?:[0-5][0-9])|(?:60)))?))?$', None], ...]