Timestamp Library
#Loading the Timestamp Library

The Timestamp library is optional. In order to use this library, 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 main.lua file, outside of any functions or other code, and you may do this by using this code:

Example: require 'timestamp';
#Method Chaining

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.

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, or false if they are not.

#Supported Methods #Constructor timestamp Timestamp(number year, number month, number day, number hour, number minutes, number seconds) timestamp Timestamp(number unixTimestamp) timestamp 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. If no parameters are given (ie, you called Timestamp()), the timestamp returned will be for 'now'.

You may also pass a UNIX timestamp.

#Timestamp:now timestamp Timestamp:now()

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

#Timestamp:today timestamp Timestamp:today()

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

#Timestamp:yesterday timestamp Timestamp:yesterday()

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

#Timestamp:tomorrow timestamp Timestamp:tomorrow()

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

#Timestamp:timezoneOffset number Timestamp:timezoneOffset()

Returns your offset, in hours, from UTC.

#Timestamp:toHuman string Timestamp:toHuman() string Timestamp:toHuman(number tzOffset)

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

#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 string Timestamp:format(string fmt)

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

Example: local timestamp = Timestamp:now(); print(timestamp:format("Today is %A, %B %d of %Y")); -- Prints something like: Today is Tuesday, October 02 of 2018
#Timestamp:addSeconds timestamp Timestamp:addSeconds(number sec)

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

#Timestamp:subSeconds timestamp Timestamp:subSeconds(number sec)

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

#Timestamp:addMinutes timestamp Timestamp:addMinutes(number min)

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

#Timestamp:subMinutes timestamp Timestamp:subMinutes(number min)

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

#Timestamp:addHours timestamp Timestamp:addHours(number hours)

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

#Timestamp:subHours timestamp Timestamp:subHours(number hours)

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

#Timestamp:addDays timestamp Timestamp:addDays(number days)

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

#Timestamp:subDays timestamp Timestamp:subDays(number days)

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

#Timestamp:addMonths timestamp Timestamp:addMonths(number months)

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

#Timestamp:subMonths timestamp Timestamp:subMonths(number months)

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

#Timestamp:addYears timestamp Timestamp:addYears(number years)

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

#Timestamp:subYears timestamp 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), otherwise returns false.

#Timestamp:isPast boolean Timestamp:isPast()

Returns true if the timestamp is in the past (ie. < now), otherwise returns false.

#Timestamp:isNow boolean Timestamp:isNow()

Returns true if the timestamp is right now (ie. == now) to the second, otherwise returns false.

#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.

This is the same as the - operator.

Example: local timestamp = Timestamp:now(); local newTimestamp = timestamp:addSeconds(90); print("Diff in seconds:", newTimestamp - timestamp); -- Should print 90 print("Diff in seconds:", newTimestamp:diffInSeconds(timestamp)); -- Should print 90 print("Diff in minutes:", newTimestamp:diffInMinutes(timestamp)); -- Should print 1 print("Diff in hours:", newTimestamp:diffInHours(timestamp)); -- Should print 0
#Timestamp:diffInMinutes number Timestamp:diffInMinutes(timestamp other)

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

#Timestamp:diffInHours number Timestamp:diffInHours(timestamp other)

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

#Timestamp:diffInDays number Timestamp:diffInDays(timestamp other)

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

Page last updated at 2018-10-02 21:54:50


Copyright 2018