time

Summit datetime library. Contains utilities for creating, modifying and comparing datetime objects.

Classes

Name Summary
DateTime

An object representing a date and time.

Functions

Name Summary
convert_timezone

Convert a datetime object into another timezone.

create

Return a date/time object from at time_string in the given format and timezone.

format

Return a string with the date/time formatted according to your specification.

is_business_hours

Return true if t falls between 9:00 am and 5:00 pm.

is_workday

Return true if t falls on a weekday, Monday – Friday.

now

Return a date/time object for the current time in the given timezone.

sleep

Pause for some number of seconds.

to_unix_ts

Convert a timestamp to the Unix seconds-since-epoch style

weekday_name

Returns a string with the name of the day of the week. eg “wednesday”

Constants

Name Type Value Summary
MONDAY

number

0

TUESDAY

number

1

WEDNESDAY

number

2

THURSDAY

number

3

FRIDAY

number

4

SATURDAY

number

5

SUNDAY

number

6

TIME_FORMAT

string

“%I:%M %p”

DATE_FORMAT

string

“%A, %B %d, %Y”

DEFAULT_INPUT_FORMAT

string

“%d%m%y”

Classes : time

DateTime

An object representing a date and time.

Fields
Name Type Summary
year

number

The year represented

month

number

The month represented

day

number

The day represented

hour

number

The hour in 24-hour format

minute

number

The minute represented

second

number

The seconds represented

microsecond

number

The microseconds represented

Functions : time

convert_timezone(t, timezone)

Convert a datetime object into another timezone. Use this function to convert timezone-aware datetime objects to other timezones.

Parameters
Name Type Default Summary

t

DateTime

Time object to convert

timezone

string

Desired timezone after conversion

Returns
Type Summary

DateTime or nil

A DateTime object which can be used with time.format or various other time library functions if successful, nil otherwise

string or nil

nil if successful, an error message otherwise

Usage
local t = time.now("UTC")  -- 2014-04-12 20:07:36.385981
local my_tz_t = time.convert_timezone(t, 'America/Chicago')
print(my_tz_t) -- 2014-04-12 15:07:36.385981

create(time_string, timezone, format)

Return a date/time object from at time_string in the given format and timezone. For example, util.time.create("09122014", "US/Central", "%d%m%Y") will return a time/date object for September 12th, 2014. If you omit the format argument, "%d%m%y" will be assumed. For a description of time format specification strings, see the Python docs.

Parameters
Name Type Default Summary

time_string

string

String indicating a date/time.

timezone

string

Timezone the created date/time object will have.

format

string

String used to decode time_string.

Returns
Type Summary

DateTime or nil

An instance of a class representing a DateTime object, if the call was successful, or nil if there was an error

string or nil

A string error description if something went wrong, or nil if successful

Usage
local time = require('summit.time')
local t, err = time.create("Mon, July 21 '14 1:46 PM", "US/Central", "%a, %B %d '%y %I:%M %p")
print(t) -- 2014-07-21 13:46:00-05:00

format(t, format)

Return a string with the date/time formatted according to your specification. For example, time.format(time.DATE_FORMAT) might return ‘Monday, March 03, 2014’ and time.format(t, "%I:%M %p") might return ‘05:53 PM’ For a description of time format specification strings, see the Python docs.

Parameters
Name Type Default Summary

t

DateTime

Time object being tested.

format

string

String being used to format the time object.

Returns
Type Summary

string

A formatted string

Usage
local time = require('summit.time')
local t = time.now('US/Central')
print(time.format(t, "%a, %B %d '%y %H:%M %p")) -- Mon, July 21 '14 13:46 PM

is_business_hours(t, start_time, end_time)

Return true if t falls between 9:00 am and 5:00 pm. If your normal business hours are at other times, 7:00 am to 3:00 pm, say, you could use time.is_business_hours(t, 700, 1500)

Parameters
Name Type Default Summary

t

DateTime

Time object being tested.

start_time

number

Integer corresponding to the opening time on a 24 hour clock.

end_time

number

Integer corresponding to the closing time on a 24 hour clock.

Returns
Type Summary

boolean

true if t falls between 9:00 am and 5:00 pm, false otherwise

Usage
local time = require('summit.time')
local t = time.now('US/Central') -- e.g. 12:30 PM
print(time.is_business_hours(t)) -- true
print(time.is_business_hours(t, 1300, 1700)) -- false

is_workday(t, start_day, end_day)

Return true if t falls on a weekday, Monday – Friday. Or if for some reason, your normal work week is Tuesday through Thursday, you can use time.is_workday(t, time.TUESDAY, time.THURSDAY)

Parameters
Name Type Default Summary

t

DateTime

Time object being tested.

start_day

number

Integer corresponding to the starting day of the work week.

end_day

number

Integer corresponding to the ending day of the work week.

Returns
Type Summary

boolean

true if t falls on a weekday (Monday – Friday), false otherwise

Usage
local time = require('summit.time')
local t = time.now('US/Central') -- e.g. a Monday
print(time.is_workday(t)) -- true
print(time.is_workday(t, time.TUESDAY, time.SATURDAY)) -- false

now(timezone)

Return a date/time object for the current time in the given timezone. Note that timezone is required. Example time zones: “US/Central”, “America/Chicago”, ‘US/Eastern", “Europe/Berlin”. For a more complete list of valid time zones, see the TZ column in the table on the following Wikipedia page: List of tz database time zones

Parameters
Name Type Default Summary

timezone

string

Timezone the function will use to return the current time.

Returns
Type Summary

DateTime

The current time in the given timezone.

Usage
local time = require('summit.time')
local t = time.now('US/Central') -- e.g. 2014-07-21 12:36:32.257369-05:00

sleep(seconds)

Pause for some number of seconds. May be a decimal, eg. sleep(0.5) to sleep for half a second.

Parameters
Name Type Default Summary

seconds

number

Number of seconds to pause.

Returns
Type Summary

nil

Usage
local time = require('summit.time')
do_something()
time.sleep(1.5)
do_something_one_point_five_seconds_later()

to_unix_ts(time)

Convert a timestamp to the Unix seconds-since-epoch style

Parameters
Name Type Default Summary

time

DateTime

A datetime object like that which is returned by time.now()

Returns
Type Summary

float

The number of seconds since epoch

Usage
local time = require('summit.time')
local t = time.now('US/Central')
print(time.to_unix_ts(t)) -- 1405965590.7589

weekday_name(t)

Returns a string with the name of the day of the week. eg “wednesday”

Parameters
Name Type Default Summary

t

DateTime

Time object being tested.

Returns
Type Summary

string

The name of the day of the week for t

Usage
local time = require('summit.time')
local t = time.now('US/Central')
print(time.weekday_name(t)) -- monday

Constants : time

MONDAY

Type: number

Value: 0

TUESDAY

Type: number

Value: 1

WEDNESDAY

Type: number

Value: 2

THURSDAY

Type: number

Value: 3

FRIDAY

Type: number

Value: 4

SATURDAY

Type: number

Value: 5

SUNDAY

Type: number

Value: 6

TIME_FORMAT

Type: string

Value: “%I:%M %p”

DATE_FORMAT

Type: string

Value: “%A, %B %d, %Y”

DEFAULT_INPUT_FORMAT

Type: string

Value: “%d%m%y”