Timestamp Class

From SolarStrike wiki
Jump to: navigation, search

Loading the Timestamp Class[edit]

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[edit]

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[edit]

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[edit]

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[edit]

class Timestamp:now()

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


Timestamp:today[edit]

class Timestamp:today()

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


Timestamp:yesterday[edit]

class Timestamp:yesterday()

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


Timestamp:tomorrow[edit]

class Timestamp:tomorrow()

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


Timestamp:timezoneOffset[edit]

number Timestamp:timezoneOffset()

Returns your offset, in hours, from UTC


Timestamp:toHuman[edit]

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:toUtc[edit]

string Timestamp:toUtc()'

string Timestamp:toUtc()

Returns the timestamp as a human-readable string in UTC format. For example: Thu, 01 Jan 1970 00:00:00 UTC


Timestamp:format[edit]

string Timestamp:format(fmt)'

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


Timestamp:addSeconds[edit]

class Timestamp:addSeconds(number sec)

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


Timestamp:subSeconds[edit]

class Timestamp:subSeconds(number sec)

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


Timestamp:addMinutes[edit]

class Timestamp:addMinutes(number min)

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


Timestamp:subMinutes[edit]

class Timestamp:subMinutes(number min)

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


Timestamp:addHours[edit]

class Timestamp:addHours(number hours)

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


Timestamp:subHours[edit]

class Timestamp:subHours(number hours)

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


Timestamp:addDays[edit]

class Timestamp:addDays(number days)

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


Timestamp:subDays[edit]

class Timestamp:subDays(number days)

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


Timestamp:addMonths[edit]

class Timestamp:addMonths(number months)

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


Timestamp:subMonths[edit]

class Timestamp:subMonths(number months)

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


Timestamp:addYears[edit]

class Timestamp:addYears(number years)

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


Timestamp:subYears[edit]

class Timestamp:subYears(number years)

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


Timestamp:isFuture[edit]

boolean Timestamp:isFuture()

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


Timestamp:isPast[edit]

boolean Timestamp:isFuture()

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


Timestamp:isNow[edit]

boolean Timestamp:isNow()

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


Timestamp:diffInSeconds[edit]

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[edit]

number Timestamp:diffInMinutes(Timestamp other)

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


Timestamp:diffInHours[edit]

number Timestamp:diffInHours(Timestamp other)

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


Timestamp:diffInDays[edit]

number Timestamp:diffInDays(Timestamp other)

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