Timestamp Class

The Timestamp class is an optional library

In order to use this class, you must require it in one of your source files (preferably main.lua) prior to use. It only needs to be required once in a single file. It is recommended you do this at the top of your file, outside of any functions or other code, and you may do this by using this code:

require('timestamp');

Method Chaining Support

The Timestamp class supports method chaining, but does not modify the base object unless explicitly stated. That is, most functions will return a new Timestamp object with the modification made. For example:

t = Timestamp:now(); -- Assign 'now' to 't'

-- Assigning a value to a timestamp
t:addSeconds(5);     -- Invalid; 't' will not be modified!
t = t:addSeconds(5); -- Valid; 't' now contains 'now' + 5 seconds.

-- Method chaining
t = Timestamp:now():addSeconds(5);  -- Also valid; 't' contains 'now' + 5 seconds.
t = Timestamp:now():addYears(1):addMonths(6):addDays(14); -- Valid; 'now' + 1 year, 6 months, and 2 weeks.

Supported Operators

Most standard operators, including >, >=, <, <=, -, and == are supported. Comparison operators will simply return a boolean indicating which timestamp came first (ie. timestamp1 < timestamp2 tests if 'timestamp1' is before 'timestamp2'). The minus/subtract operator (-) returns the difference, in seconds, between two timestamps (and may be negative if timestamp1 < timestamp2). Finally, the equality operator (==) returns true if the two timestamps are at the same time.

= Supported Methods =.

Constructor

class Timestamp(number year, number month, number day, number hour, number minutes, number seconds)

class Timestamp(number unixTime)

class Timestamp()

Creates a Timestamp object out of an arbitrarily defined date and time. Any field that is nil should be assumed from the current time. That is, leaving 'year' as nil will assume the real, current year pulled from your computer's clock, while any given fields will be filled with the information you have provided.

You may also pass a UNIX timestamp.

Timestamp:now

class Timestamp:now()

Returns a Timestamp object that contains the current date/time value of your computer's clock.

Timestamp:today

class Timestamp:today()

Returns a Timestamp object that contains the current date with time starting at 12:00AM.

Timestamp:yesterday

class Timestamp:yesterday()

Exactly like Timestamp:today() except it is for yesterday's date/time.

Timestamp:tomorrow

class Timestamp:tomorrow()

Exactly like Timestamp:today() except it is for tomorrow's date/time.

Timestamp:toHuman

string Timestamp:toHuman()'

string Timestamp:toHuman(number tz_offset)

Returns the timestamp as a human-readable string and (optionally) including tz_offset to represent the timezone's offset from the prime meridian. If tz_offset is not given, the time will be using local time. tz_ofset = 0 will return time in UTC.

Timestamp:format

string Timestamp:format(fmt)'

Returns the timestamp in any format requested, using standard ANSI C date/time formatting options.

Timestamp:addSeconds

class Timestamp:addSeconds(number sec)

Returns a new Timestamp object with 'sec' seconds added on.

Timestamp:subSeconds

class Timestamp:subSeconds(number sec)

Returns a new Timestamp object with 'sec' seconds subtracted.

Timestamp:addMinutes

class Timestamp:addMinutes(number min)

Returns a new Timestamp object with 'min' minutes added on.

Timestamp:subMinutes

class Timestamp:subMinutes(number min)

Returns a new Timestamp object with 'min' minutes subtracted.

Timestamp:addHours

class Timestamp:addHours(number hours)

Returns a new Timestamp object with 'hours' hours added on.

Timestamp:subHours

class Timestamp:subHours(number hours)

Returns a new Timestamp object with 'hours' hours subtracted.

Timestamp:addDays

class Timestamp:addDays(number days)

Returns a new Timestamp object with 'days' days added on.

Timestamp:subDays

class Timestamp:subDays(number days)

Returns a new Timestamp object with 'days' days subtracted.

Timestamp:addMonths

class Timestamp:addMonths(number months)

Returns a new Timestamp object with 'months' months added on.

Timestamp:subMonths

class Timestamp:subMonths(number months)

Returns a new Timestamp object with 'months' months subtracted.

Timestamp:addYears

class Timestamp:addYears(number years)

Returns a new Timestamp object with 'years' years added on.

Timestamp:subYears

class Timestamp:subYears(number years)

Returns a new Timestamp object with 'years' years subtracted.

Timestamp:isFuture

boolean Timestamp:isFuture()

Returns true if the timestamp is in the future (ie. > now).

Timestamp:isPast

boolean Timestamp:isFuture()

Returns true if the timestamp has already past (ie. < now).

Timestamp:isNow

boolean Timestamp:isNow()

Returns true if the timestamp is right now (ie. == now).

Timestamp:diffInSeconds

number Timestamp:diffInSeconds(Timestamp other)

Returns the number of seconds between two timestamps. This number may be negative if 'other' is in the future in relation to the original timestamp.

Timestamp:diffInMinutes

number Timestamp:diffInMinutes(Timestamp other)

Exactly like Timestamp:diffInSeconds() except it returns the difference in minutes.

Timestamp:diffInHours

number Timestamp:diffInHours(Timestamp other)

Exactly like Timestamp:diffInSeconds() except it returns the difference in hours.

Timestamp:diffInDays

number Timestamp:diffInDays(Timestamp other)

Exactly like Timestamp:diffInSeconds() except it returns the difference in days.