PTypes: date/time: datetime

Top: Basic types: Date/time: Datetime type

#include <ptime.h>

typedef large datetime;

datetime  now(bool utc = true);
int       days(datetime d);
int       msecs(datetime d);
datetime  mkdt(int days, int msecs);
bool      isvalid(datetime d);
void      tzupdate();
int       tzoffset();
string    dttostring(datetime d, const char* fmt);
string    nowstring(const char* fmt, bool utc = true);
datetime  utodatetime(time_t u);

datetime now(bool utc = true) returns the current date/time. The returned value can be either the local time or the Universal Coordinated Time (UTC, aka GMT), depending on the parameter utc. It is recommended to manipulate with the UTC time internally in your application whenever possible (f.ex. when it's not needed to display the time to the user), since in many countries the local time may be automatically adjusted when entering or leaving the daylight saving period, which may confuse your application. On the contrary, the UTC time never changes. That's why all modern operating systems rely on the UTC time internally. (See also tzupdate() below for additional notes).

int days(datetime d) returns the number of days since the beginning of the calendar contained in the datetime value d.

int msecs(datetime d) returns the number of milliseconds since midnight contained in the datetime value d.

datetime mkdt(int days, int msecs) calculates the datetime value from days and msecs parameters. Days is the number of days since the beginning of the calendar, and msecs is the number of milliseconds since midnight. No checks are made for validity of these values. There exists an easier way to build a datetime value using encodedate() and encodetime() functions having the year, month and day numbers, as well as (not necessarily) the hour, minute, second and millisecond values.

bool isvalid(datetime d) checks a datetime value for validity. The value of d is valid if it holds a time stamp between 01/01/0001 and 12/31/9999.

void tzupdate() updates the internal timezone information, which affects the value of local time returned by now() and nowstring(). If your application is supposed to be running infinitely (e.g. if it's a network daemon), you might want to update the internal timezone information from time to time in order to return correct local time to the user on DST adjustment days. Depending on the precision of local time you wish to show to the user, you can call this function, for example, every minute or every hour. Without this, the local time may become incorrect at the moment of DST adjustment, which occurs twice a year in most countries.

int tzoffset() returns the time zone offset in minutes. This value is negative in the West. Multiplying this value by 60000 (i.e. the offset in milliseconds) and adding it to the UTC datetime value will give the local time.

string dttostring(datetime d, const char* fmt) converts a datetime value to string representation as specified by fmt. The syntax of the format specifier is the same as for strftime() (please, refer to the corresponding manual pages in your programming environment). Note that there might be slight incompatibilities between different implementations of strftime().

string nowstring(const char* fmt, bool utc = true) returns a string representing the current time in a format specified by fmt. Utc specifies whether the local time or the UTC time is required. Like for dttostring(), the syntax of the format specifier fmt is the same as for the system function strftime().

datetime utodatetime(time_t u) converts UNIX time_t value to PTypes datetime.

PTypes home