Timestamp handling

Timestamp handling — Convenience functions for dealing with timestamps and dates

Synopsis

#include <zeitgeist.h>

#define             ZEITGEIST_TIMESTAMP_SECOND
#define             ZEITGEIST_TIMESTAMP_MINUTE
#define             ZEITGEIST_TIMESTAMP_HOUR
#define             ZEITGEIST_TIMESTAMP_DAY
#define             ZEITGEIST_TIMESTAMP_WEEK
#define             ZEITGEIST_TIMESTAMP_YEAR
gint64              zeitgeist_timestamp_for_now         (void);
gint64              zeitgeist_timestamp_from_date       (GDate *date);
gint64              zeitgeist_timestamp_from_dmy        (GDateDay day,
                                                         GDateMonth month,
                                                         GDateYear year);
gint64              zeitgeist_timestamp_from_iso8601    (const gchar *datetime);
gint64              zeitgeist_timestamp_from_timeval    (GTimeVal *tv);
gint64              zeitgeist_timestamp_next_midnight   (gint64 timestamp);
gint64              zeitgeist_timestamp_prev_midnight   (gint64 timestamp);
void                zeitgeist_timestamp_to_date         (gint64 timestamp,
                                                         GDate *date);
gchar *             zeitgeist_timestamp_to_iso8601      (gint64 timestamp);
void                zeitgeist_timestamp_to_timeval      (gint64 timestamp,
                                                         GTimeVal *tv);

Description

A suite of convenience functions for dealing with timestamps and dates.

Zeitgeist timestamps are represented as gint64s with the number of milliseconds since the Unix Epoch.

Details

ZEITGEIST_TIMESTAMP_SECOND

#define ZEITGEIST_TIMESTAMP_SECOND G_GINT64_CONSTANT (1000)

A second represented as a Zeitgeist timestamp (ie. 1000ms)


ZEITGEIST_TIMESTAMP_MINUTE

#define ZEITGEIST_TIMESTAMP_MINUTE G_GINT64_CONSTANT (60000)

A minute represented as a Zeitgeist timestamp (ie. 60000ms)


ZEITGEIST_TIMESTAMP_HOUR

#define ZEITGEIST_TIMESTAMP_HOUR G_GINT64_CONSTANT (3600000)

An hour represented as a Zeitgeist timestamp (ie. 3600000ms)


ZEITGEIST_TIMESTAMP_DAY

#define ZEITGEIST_TIMESTAMP_DAY G_GINT64_CONSTANT (86400000)

A day represented as a Zeitgeist timestamp (ie. 86400000ms)


ZEITGEIST_TIMESTAMP_WEEK

#define ZEITGEIST_TIMESTAMP_WEEK G_GINT64_CONSTANT (604800000)

A week represented as a Zeitgeist timestamp (ie. 604800000ms)


ZEITGEIST_TIMESTAMP_YEAR

#define ZEITGEIST_TIMESTAMP_YEAR G_GINT64_CONSTANT (31556952000)

A year represented as a Zeitgeist timestamp (ie. 31556952000ms). Be warned that a year is not 365 days, but in fact 365.2425 days to account for leap years.


zeitgeist_timestamp_for_now ()

gint64              zeitgeist_timestamp_for_now         (void);

Get the timestamp for the current system time

Returns :

The timestamp for the current system time. Ie. the number of milliseconds since the Unix Epoch

zeitgeist_timestamp_from_date ()

gint64              zeitgeist_timestamp_from_date       (GDate *date);

Convert a GDate to a Zeitgeist timestamp.

date :

A GDate to convert

Returns :

date as a timestamp in milliseconds since the Epoch. The timestamp is guaranteed to be rounded off to the midnight of the given date.

zeitgeist_timestamp_from_dmy ()

gint64              zeitgeist_timestamp_from_dmy        (GDateDay day,
                                                         GDateMonth month,
                                                         GDateYear year);

Convert a day, month, year tuple into a Zeitgeist timestamp

day :

The day of the month represented as a GDateDay

month :

The month of the year represented as a GDateMonth

year :

The year represented as a GDateYear

Returns :

Input data as a timestamp in milliseconds since the Epoch or -1 in case the provided data does not constitute a valid date. If the date is valid the returned timestamp is guaranteed to be rounded off to the midnight of the given date

zeitgeist_timestamp_from_iso8601 ()

gint64              zeitgeist_timestamp_from_iso8601    (const gchar *datetime);

Parse a timestamp from a ISO8601 encoded string.

datetime :

A string containing an iso8601 conforming datetime specification

Returns :

The timestamp represented by datetime, or -1 on failure to parse datetime

zeitgeist_timestamp_from_timeval ()

gint64              zeitgeist_timestamp_from_timeval    (GTimeVal *tv);

tv :

A GTimeVal instance

Returns :

A gint64 with the total number of milliseconds since the Unix Epoch

zeitgeist_timestamp_next_midnight ()

gint64              zeitgeist_timestamp_next_midnight   (gint64 timestamp);

Calculate the timestamp for the next midnight after timestamp

timestamp :

The Zeitgeist timestamp to find the next midnight for

Returns :

Returns the timestamp for the first midnight after timestamp. If timestamp is already midnight (down to the millisecond) this method will return the value for the next midnight. In other words you can call this method recursively in order to iterate, forwards in time, over midnights.

zeitgeist_timestamp_prev_midnight ()

gint64              zeitgeist_timestamp_prev_midnight   (gint64 timestamp);

Calculate the timestamp for the midnight just before timestamp

timestamp :

The Zeitgeist timestamp to find the previous midnight for

Returns :

Returns the timestamp for the first midnight just before timestamp. If timestamp is already midnight (down to the millisecond) this method will return the value for the midnight before. In other words you can call this method recursively in order to iterate, backwards in time, over midnights.

zeitgeist_timestamp_to_date ()

void                zeitgeist_timestamp_to_date         (gint64 timestamp,
                                                         GDate *date);

Write a timestamp to a GDate structure

timestamp :

The Zeitgeist timestamp to convert to a GDate

date :

The place to store the result in. Must be non-NULL

zeitgeist_timestamp_to_iso8601 ()

gchar *             zeitgeist_timestamp_to_iso8601      (gint64 timestamp);

Convert a timestamp to a human readable ISO8601 format

timestamp :

A Zeitgeist timestamp in ms since the Epoch

Returns :

A newly allocated string containing the ISO8601 format of timestamp. Free with g_free().

zeitgeist_timestamp_to_timeval ()

void                zeitgeist_timestamp_to_timeval      (gint64 timestamp,
                                                         GTimeVal *tv);

Write a Zeitgeist timestamp to a GTimeVal instance. Note that Zeitgeist uses only a millisecond resolution for where GTimeVal uses a microsecond resolution, meaning that the lower three digits of tv.tv_usec will be 0.

timestamp :

A gint64 with a number of milliseconds since the Unix Epoch

tv :

A GTimeVal instance to store the result in